shennian 0.2.77 → 0.2.83

package/dist/scripts/wechat-rpa-win-visual.mjs

@@ -7,7 +7,8 @@ import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { selectDownloadedAttachment } from './wechat-rpa-download-candidates.mjs'
+import { recognizeWindowsScreenshot } from './wechat-rpa-windows-ocr.mjs'
+import { parseWeChatLayout } from './wechat-rpa-lab/layout/parser.mjs'
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const helperBridge = path.join(repoRoot, 'scripts/wechat-rpa-win.mjs')
@@ -17,7 +18,7 @@ const SECTION_LABELS = new Set(['群聊', '联系人', '聊天记录', '公众
 function printHelp() {
   console.log(`Usage:
   node scripts/wechat-rpa-win-visual.mjs --group ABC --recent-limit 5
-  node scripts/wechat-rpa-win-visual.mjs --group ABC --reply-text "我是 AI" --ocr-url https://shennian.net/integrations/wechat-rpa/ocr --token <token>
+  node scripts/wechat-rpa-win-visual.mjs --group ABC --reply-text "我是 AI" --ocr-fixture C:\\tmp\\search-ocr.json
   node scripts/wechat-rpa-win-visual.mjs --group ABC --file C:\\tmp\\demo.png --file C:\\tmp\\demo.mp4 --ocr-fixture C:\\tmp\\search-ocr.json
 
 Options:
@@ -28,16 +29,22 @@ Options:
   --capture-dir <dir>     Directory for screenshots and debug JSON. Default: temp shennian-wechat-rpa-win-visual-*.
   --download-attachments-dir <dir>
                           Copy clicked inbound attachments into this directory.
+  --download-expected-token <token>
+                          Extra filename/token for cache-only download lookup. Repeatable.
+  --download-limit <n>    Maximum inbound attachments to try in one run. Defaults to 1.
+  --allow-right-click-download
+                          Allow risky right-click Copy fallback when cache-only lookup misses. Disabled by default.
+  --allow-search-open     Allow opening a group through the WeChat search panel. Disabled by default on Windows live runs.
   --no-download-attachments
                           Keep inbound attachments as metadata-only/pending-download.
-  --ocr-url <url>         Shennian OCR endpoint, e.g. /integrations/wechat-rpa/ocr.
-  --token <token>         Bearer token for --ocr-url. Also reads WECHAT_RPA_OCR_TOKEN.
+  --ocr-url <url>         Deprecated; accepted for compatibility but ignored.
+  --token <token>         Deprecated; accepted for compatibility but ignored.
   --ocr-fixture <path>    Local OCR fixture JSON for deterministic selection tests/debugging.
   --helper <path>         Override native helper exe passed through to scripts/wechat-rpa-win.mjs.
   --open-timeout-ms <n>   Timeout waiting for title confirmation. Default: 12000.
   --dry-run              Open/read only; do not send reply-text/files.
 
-This is the Windows commercial baseline visual RPA orchestrator: WeChat foreground + screenshot + OCR boxes + native click/paste/press.`)
+This is the Windows commercial baseline visual RPA orchestrator: WeChat foreground + screenshot + local OCR boxes + native click/paste/press.`)
 }
 
 function takeOption(argv, name) {
@@ -70,10 +77,21 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms))
 }
 
+function psSingleQuoted(value) {
+  return String(value).replace(/'/g, "''")
+}
+
 export function normalizeConversationName(value) {
-  return String(value || '')
+  const compact = String(value || '')
     .replace(/[\s\u200b\u200c\u200d]+/g, '')
-    .replace(/[（(]\d+[)）]$/g, '')
+    .replace(/夕卜/g, '外')
+    .replace(/氵则/g, '测')
+    .replace(/氵則/g, '测')
+    .replace(/讠羊/g, '群')
+    .replace(/訁羊/g, '群')
+  return compact
+    .replace(/[（(]\d+[)）]\d*$/g, '')
+    .replace(/([\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}])[0０]{1,3}$/u, '$1')
     .trim()
     .toLowerCase()
 }
@@ -126,7 +144,8 @@ export function findConversationInSearchResults(observations, targetName) {
       })
     : []
 
-  const candidates = sectionCandidates.length > 0 ? sectionCandidates : exactCandidates
+  const fallbackCandidates = exactCandidates.filter(item => isLikelySearchResultCandidate(item.row))
+  const candidates = sectionCandidates.length > 0 ? sectionCandidates : fallbackCandidates.length > 0 ? fallbackCandidates : exactCandidates
   if (candidates.length === 0) return null
 
   return candidates
@@ -145,10 +164,65 @@ export function findConversationInSearchResults(observations, targetName) {
     .sort((a, b) => b.score - a.score)[0].row
 }
 
+function isLikelySearchResultCandidate(row) {
+  const box = row?.box || row
+  if (!box) return false
+  const x = Number(box.x || 0)
+  const y = Number(box.y || 0)
+  const width = Number(box.width || 0)
+  const height = Number(box.height || 0)
+  const normalized = Math.max(Math.abs(x), Math.abs(y), Math.abs(width), Math.abs(height)) <= 1
+  if (normalized) return x >= 0.08 && x <= 0.55 && y >= 0.12 && y <= 0.72
+  return x >= 120 && x <= 620 && y >= 120 && y <= 720
+}
+
+export function findConversationInLeftList(observations, targetName) {
+  const target = normalizeConversationName(targetName)
+  if (!target) throw new Error('targetName is required')
+  const candidates = (Array.isArray(observations) ? observations : [])
+    .filter(row => row?.box && normalizeConversationName(observationText(row)) === target && isLikelyLeftListConversation(row))
+    .map(row => ({ row, center: centerOfBox(row.box), confidence: observationConfidence(row) }))
+  if (!candidates.length) return null
+  return candidates
+    .map(item => ({
+      ...item,
+      score: item.confidence * 100 - Math.abs(item.center.x - 220) * 0.01 - item.center.y * 0.001,
+    }))
+    .sort((a, b) => b.score - a.score)[0].row
+}
+
+function isLikelyLeftListConversation(row) {
+  const box = row?.box || row
+  if (!box) return false
+  const x = Number(box.x || 0)
+  const y = Number(box.y || 0)
+  const width = Number(box.width || 0)
+  const height = Number(box.height || 0)
+  const normalized = Math.max(Math.abs(x), Math.abs(y), Math.abs(width), Math.abs(height)) <= 1
+  if (normalized) return x >= 0.10 && x <= 0.34 && y >= 0.12 && y <= 0.92
+  return x >= 120 && x <= 460 && y >= 120 && y <= 900
+}
+
 export function findTitleConfirmation(observations, targetName) {
   const target = normalizeConversationName(targetName)
   const rows = Array.isArray(observations) ? observations : []
-  return rows.find(row => normalizeConversationName(observationText(row)) === target) || null
+  return rows.find(row => normalizeConversationName(observationText(row)) === target && isLikelyMainTitle(row)) || null
+}
+
+export function findSendButtonObservation(observations) {
+  return (Array.isArray(observations) ? observations : [])
+    .filter(row => /^(发送|send)$/i.test(normalizedMessageText(observationText(row))) && isLikelyComposerSendButton(row))
+    .sort((left, right) => observationConfidence(right) - observationConfidence(left))[0] || null
+}
+
+export function findComposerPendingAttachmentObservation(observations) {
+  return (Array.isArray(observations) ? observations : [])
+    .filter(row => looksLikeComposerPendingAttachmentText(observationText(row)) && isLikelyComposerPendingAttachment(row))
+    .sort((left, right) => observationConfidence(right) - observationConfidence(left))[0] || null
+}
+
+export function findComposerDirtyObservation(observations) {
+  return findSendButtonObservation(observations) || findComposerPendingAttachmentObservation(observations)
 }
 
 export function isRetryableOcrError(status, body) {
@@ -184,6 +258,7 @@ export function geometryPoint(capturePayload, kind) {
     search: [0.186, 0.087],
     // Right-side composer: avoid the left search overlay and click inside the text area.
     input: [0.58, 0.92],
+    fileInput: [0.58, 0.86],
     send: [0.932, 0.945],
   }
   const pair = presets[kind]
@@ -258,10 +333,82 @@ async function capture(region, options, label) {
   return { result, payload: result?.payload, file, imageSize: readPngSize(file) }
 }
 
+async function captureWithRetry(region, options, label, retry = {}) {
+  const attempts = Number(retry.attempts || 5)
+  const delayMs = Number(retry.delayMs || 700)
+  let lastError = null
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await capture(region, options, label)
+    } catch (error) {
+      lastError = error
+      if (!isRetryableWindowCaptureError(error) || attempt === attempts) break
+      await sleep(delayMs)
+    }
+  }
+  throw lastError
+}
+
+async function waitForStableWindow(options, label, retry = {}) {
+  const attempts = Number(retry.attempts || 6)
+  const delayMs = Number(retry.delayMs || 650)
+  let previous = null
+  let latest = null
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    latest = await captureWithRetry('window', options, `${label}-stability-${attempt}`, { attempts: 2, delayMs })
+    if (previous && areSameWindowBounds(previous.payload, latest.payload)) return latest
+    previous = latest
+    await sleep(delayMs)
+  }
+  return latest
+}
+
+function areSameWindowBounds(left, right) {
+  const a = left?.mainWindow?.bounds || left?.bounds
+  const b = right?.mainWindow?.bounds || right?.bounds
+  if (!a || !b) return false
+  return ['x', 'y', 'width', 'height'].every(key => Math.abs(Number(a[key]) - Number(b[key])) <= 2)
+}
+
+export function isRetryableWindowCaptureError(error) {
+  return /Cannot locate WeChat main window via (Win32|UI Automation)/i.test(String(error?.message || error || ''))
+}
+
+export function assertSearchOpenAllowed(options, targetGroup) {
+  if (options?.allowSearchOpen) return true
+  throw new Error(
+    `Target group '${targetGroup || options?.group || ''}' is not the current title or visible in the left list; ` +
+      'search-panel opening is disabled for Windows safety because it can make WeChat non-enumerable.',
+  )
+}
+
 async function click(point, options, extra = []) {
   return runBridge(['click', '--x', String(point.x), '--y', String(point.y), ...extra], options)
 }
 
+async function rightClick(point, options, extra = []) {
+  return click(point, options, ['--right', ...extra])
+}
+
+async function readClipboard(options) {
+  const result = await runBridge(['read-clipboard'], options)
+  return result?.payload || result
+}
+
+function writeDebugArtifact(options, name, value) {
+  if (!options?.captureDir) return
+  fs.writeFileSync(path.join(options.captureDir, name), `${JSON.stringify(value, null, 2)}\n`)
+}
+
+export function prepareCaptureDir(captureDir) {
+  fs.mkdirSync(captureDir, { recursive: true })
+  for (const entry of fs.readdirSync(captureDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue
+    if (!/\.(png|json)$/i.test(entry.name)) continue
+    fs.rmSync(path.join(captureDir, entry.name), { force: true })
+  }
+}
+
 async function pasteText(text, options) {
   return runBridge(['paste-text', '--text', text], options)
 }
@@ -274,59 +421,358 @@ async function press(keys, options) {
   return runBridge(['press', '--keys', keys], options)
 }
 
+async function dismissMenus(options, count = 2) {
+  try {
+    return await runBridge(['dismiss-menus', '--count', String(count)], options)
+  } catch (error) {
+    if (process.platform !== 'win32') throw error
+    return dismissMenusWithPowerShell(count)
+  }
+}
+
+async function dismissMenusWithPowerShell(count = 2) {
+  const finalCount = Math.max(1, Math.min(5, Number(count) || 2))
+  const script = `
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public static class KeyboardDismiss {
+  [DllImport("user32.dll")]
+  public static extern void keybd_event(byte bVk, byte bScan, uint dwFlags, UIntPtr dwExtraInfo);
+}
+
+"@
+for ($i = 0; $i -lt ${finalCount}; $i += 1) {
+  [KeyboardDismiss]::keybd_event(0x1B, 0, 0, [UIntPtr]::Zero)
+  Start-Sleep -Milliseconds 20
+  [KeyboardDismiss]::keybd_event(0x1B, 0, 0x0002, [UIntPtr]::Zero)
+  Start-Sleep -Milliseconds 90
+}
+@{ ok = $true; command = "dismiss-menus-powershell"; count = ${finalCount} } | ConvertTo-Json -Compress
+`
+  const encoded = Buffer.from(script, 'utf16le').toString('base64')
+  const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded], {
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  let stdout = ''
+  let stderr = ''
+  child.stdout.setEncoding('utf8')
+  child.stderr.setEncoding('utf8')
+  child.stdout.on('data', chunk => { stdout += chunk })
+  child.stderr.on('data', chunk => { stderr += chunk })
+  const exitCode = await new Promise((resolve, reject) => {
+    child.on('error', reject)
+    child.on('close', resolve)
+  })
+  if (exitCode !== 0) {
+    throw new Error(stderr.trim() || stdout.trim() || `dismiss-menus PowerShell exited ${exitCode}`)
+  }
+  try {
+    return JSON.parse(stdout.trim())
+  } catch {
+    return { ok: true, command: 'dismiss-menus-powershell', count: finalCount, stdout: stdout.trim() }
+  }
+}
+
+async function verifyPostRunSafety(options, artifacts) {
+  try {
+    const safetyCapture = await captureWithRetry('window', options, 'post-run-safety', { attempts: 4, delayMs: 800 })
+    artifacts.push(safetyCapture.file)
+    return {
+      ok: true,
+      artifact: safetyCapture.file,
+      bounds: safetyCapture.payload?.mainWindow?.bounds || safetyCapture.payload?.bounds,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    writeDebugArtifact(options, 'post-run-safety-error.json', {
+      ok: false,
+      message,
+    })
+    throw new Error(
+      `P0 Windows WeChat safety check failed after the visual flow: ${message}. ` +
+        'This run is not eligible for pass-rate or TODO acceptance even if the business action appeared to succeed.',
+    )
+  }
+}
+
 async function recognizeScreenshot(capture, options, purpose) {
-  if (options.ocrFixture) {
-    const fixture = JSON.parse(fs.readFileSync(options.ocrFixture, 'utf8'))
-    if (Array.isArray(fixture)) return { ok: true, purpose, observations: fixture }
-    if (fixture[purpose]) return fixture[purpose]
-    if (Array.isArray(fixture.observations)) return fixture
-    if (fixture && typeof fixture === 'object') {
-      throw new Error(`OCR fixture does not contain purpose '${purpose}'.`)
+  const ocr = await recognizeWindowsScreenshot(capture, { ...options, isRetryableOcrError }, purpose)
+  return {
+    ...ocr,
+    layout: buildWindowsCoreLayout(capture, ocr.observations, {
+      targetGroup: options.group,
+      purpose,
+    }),
+  }
+}
+
+export function buildWindowsCoreLayout(capture, observations, options = {}) {
+  const bounds = capture?.payload?.mainWindow?.bounds || capture?.payload?.bounds || capture?.bounds || {}
+  const imageSize = capture?.imageSize || options.imageSize || {}
+  const width = Number(imageSize.width || bounds.width || 0)
+  const height = Number(imageSize.height || bounds.height || 0)
+  const windowWidth = Number(bounds.width || width || 1)
+  const windowHeight = Number(bounds.height || height || 1)
+  const screenshot = {
+    path: capture?.file || options.imagePath || '',
+    width,
+    height,
+    scale: width && windowWidth ? width / windowWidth : 1,
+    scaleX: width && windowWidth ? width / windowWidth : 1,
+    scaleY: height && windowHeight ? height / windowHeight : width && windowWidth ? width / windowWidth : 1,
+  }
+  const window = {
+    x: Number(bounds.x || 0),
+    y: Number(bounds.y || 0),
+    width: windowWidth,
+    height: windowHeight,
+    title: '微信',
+    ownerName: 'WeChat',
+  }
+  const ocr = (Array.isArray(observations) ? observations : []).map((item) => {
+    if (!item?.box || item.x != null) return item
+    return {
+      ...item,
+      x: item.box.x,
+      y: item.box.y,
+      width: item.box.width,
+      height: item.box.height,
     }
-    return fixture
+  })
+  return parseWeChatLayout({
+    ocr,
+    screenshot,
+    window,
+    targetGroup: options.targetGroup || options.group || '',
+  })
+}
+
+export function summarizeCoreLayout(layout) {
+  const currentTitle = layout?.currentTitle || ''
+  return {
+    currentTitle,
+    targetGroupVisible: Boolean(layout?.targetGroupVisible || currentTitle),
+    leftConversationCount: Array.isArray(layout?.leftConversationList?.items) ? layout.leftConversationList.items.length : 0,
+    searchResultCount: Array.isArray(layout?.searchResults?.sections)
+      ? layout.searchResults.sections.reduce((total, section) => total + (Array.isArray(section.items) ? section.items.length : 0), 0)
+      : 0,
+    messageCount: Array.isArray(layout?.messageArea?.messages) ? layout.messageArea.messages.length : 0,
+    attachmentCount: Array.isArray(layout?.attachmentBubbles) ? layout.attachmentBubbles.length : 0,
+    inputBox: layout?.inputBox?.rect || null,
+    messageArea: layout?.messageArea?.rect || null,
   }
-  if (!options.ocrUrl) {
-    throw new Error('OCR is required for visual flow. Pass --ocr-url/--token or --ocr-fixture.')
+}
+
+export function summarizeOcrEvidence(ocr = {}) {
+  const observations = Array.isArray(ocr?.observations) ? ocr.observations : []
+  return {
+    provider: ocr?.provider || '',
+    language: ocr?.language || '',
+    durationMs: Number(ocr?.durationMs || 0),
+    observationCount: observations.length,
+    lineCount: observations.filter(item => item?.providerKind === 'line').length,
+    wordCount: observations.filter(item => item?.providerKind === 'word').length,
   }
-  const token = options.token || process.env.WECHAT_RPA_OCR_TOKEN || ''
-  if (!token) throw new Error('Missing OCR bearer token. Pass --token or WECHAT_RPA_OCR_TOKEN.')
-  const imageBase64 = fs.readFileSync(capture.file).toString('base64')
-  const maxAttempts = Math.max(1, Number(options.ocrRetries || 2) + 1)
-  let lastError = null
-  let response = null
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    response = await fetch(options.ocrUrl, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({
-        imageBase64,
-        mimeType: 'image/png',
-        purpose,
-        conversationName: options.group,
-        channelId: options.channelId,
-      }),
-      signal: AbortSignal.timeout(options.ocrTimeoutMs),
-    })
-    if (response.ok) break
-    const body = await response.text()
-    lastError = `OCR request failed: ${response.status} ${body}`
-    if (attempt >= maxAttempts || !isRetryableOcrError(response.status, body)) {
-      throw new Error(lastError)
+}
+
+export async function detectNewOutboundBubble(beforeFile, afterFile) {
+  return detectNewOutboundVisualChange(beforeFile, afterFile, {
+    kind: 'text-bubble',
+    minimumPixels: 250,
+    predicate: 'green',
+    topRatio: 0.45,
+    bottomRatio: 0.88,
+  })
+}
+
+export async function detectNewOutboundAttachmentBubble(beforeFile, afterFile) {
+  return detectNewOutboundVisualChange(beforeFile, afterFile, {
+    kind: 'attachment-bubble',
+    minimumPixels: 900,
+    predicate: 'non-background',
+    topRatio: 0.18,
+    bottomRatio: 0.84,
+  })
+}
+
+export function classifyComposerPendingAttachmentVisualMetrics(metrics = {}) {
+  const width = Number(metrics.width || 0)
+  const height = Number(metrics.height || 0)
+  const grayPixels = Number(metrics.grayPixels || 0)
+  const sampledPixels = Number(metrics.sampledPixels || 0)
+  const grayRatio = sampledPixels > 0 ? grayPixels / sampledPixels : Number(metrics.grayRatio || 0)
+  const box = metrics.box || {}
+  const boxWidth = Number(box.width || 0)
+  const boxHeight = Number(box.height || 0)
+  const boxY = Number(box.y || 0)
+  return Boolean(
+    width > 0
+    && height > 0
+    && grayPixels >= 1000
+    && grayRatio >= 0.08
+    && boxWidth >= width * 0.12
+    && boxHeight >= 18
+    && boxY >= height * 0.88
+  )
+}
+
+export async function detectComposerPendingAttachmentVisual(filePath) {
+  if (!filePath) return { ok: false, reason: 'missing image path' }
+  const script = `
+Add-Type -AssemblyName System.Drawing
+$image = [System.Drawing.Bitmap]::FromFile('${psSingleQuoted(filePath)}')
+try {
+  $left = [int]($image.Width * 0.34)
+  $right = [int]($image.Width * 0.92)
+  $top = [int]($image.Height * 0.90)
+  $bottom = [int]($image.Height * 0.995)
+  $grayPixels = 0
+  $sampledPixels = 0
+  $minX = $image.Width
+  $minY = $image.Height
+  $maxX = 0
+  $maxY = 0
+  for ($y = $top; $y -lt $bottom; $y += 2) {
+    for ($x = $left; $x -lt $right; $x += 2) {
+      $pixel = $image.GetPixel($x, $y)
+      $sampledPixels += 1
+      $spread = [Math]::Max([Math]::Abs($pixel.R - $pixel.G), [Math]::Max([Math]::Abs($pixel.G - $pixel.B), [Math]::Abs($pixel.R - $pixel.B)))
+      $isCardGray = $pixel.R -ge 228 -and $pixel.R -le 246 -and $pixel.G -ge 228 -and $pixel.G -le 246 -and $pixel.B -ge 228 -and $pixel.B -le 246 -and $spread -le 8
+      if ($isCardGray) {
+        $grayPixels += 1
+        if ($x -lt $minX) { $minX = $x }
+        if ($y -lt $minY) { $minY = $y }
+        if ($x -gt $maxX) { $maxX = $x }
+        if ($y -gt $maxY) { $maxY = $y }
+      }
+    }
+  }
+  $grayRatio = 0
+  if ($sampledPixels -gt 0) { $grayRatio = $grayPixels / $sampledPixels }
+  @{
+    kind = "composer-pending-attachment-visual"
+    width = $image.Width
+    height = $image.Height
+    sampledPixels = $sampledPixels
+    grayPixels = $grayPixels
+    grayRatio = $grayRatio
+    scan = @{ left = $left; right = $right; top = $top; bottom = $bottom; step = 2 }
+    box = @{ x = $minX; y = $minY; width = [Math]::Max(0, $maxX - $minX); height = [Math]::Max(0, $maxY - $minY) }
+  } | ConvertTo-Json -Depth 4 -Compress
+} finally {
+  $image.Dispose()
+}
+`
+  const encoded = Buffer.from(script, 'utf16le').toString('base64')
+  const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded], {
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  let stdout = ''
+  let stderr = ''
+  child.stdout.setEncoding('utf8')
+  child.stderr.setEncoding('utf8')
+  child.stdout.on('data', chunk => { stdout += chunk })
+  child.stderr.on('data', chunk => { stderr += chunk })
+  const exitCode = await new Promise((resolve, reject) => {
+    child.on('error', reject)
+    child.on('close', resolve)
+  })
+  if (exitCode !== 0) return { ok: false, reason: stderr.trim() || `powershell exited ${exitCode}` }
+  try {
+    const metrics = JSON.parse(stdout.trim())
+    return {
+      ...metrics,
+      ok: classifyComposerPendingAttachmentVisualMetrics(metrics),
     }
-    await sleep(400 * attempt)
+  } catch {
+    return { ok: false, reason: stdout.trim() || 'invalid composer visual detector JSON' }
   }
-  const json = await response.json()
-  const debugPath = capture.file.replace(/\.png$/i, `-${purpose}.ocr.json`)
-  fs.writeFileSync(debugPath, `${JSON.stringify(json, null, 2)}\n`)
-  return json
 }
 
-function summarizeObservations(observations, limit) {
+export function attachmentVisualBeforeFile(opened = {}, pendingCapture = {}) {
+  return pendingCapture?.file || opened?.file || null
+}
+
+async function detectNewOutboundVisualChange(beforeFile, afterFile, detector) {
+  if (!beforeFile || !afterFile) return { ok: false, reason: 'missing image path', kind: detector.kind }
+  const script = `
+Add-Type -AssemblyName System.Drawing
+$before = [System.Drawing.Bitmap]::FromFile('${psSingleQuoted(beforeFile)}')
+$after = [System.Drawing.Bitmap]::FromFile('${psSingleQuoted(afterFile)}')
+try {
+  if ($before.Width -ne $after.Width -or $before.Height -ne $after.Height) {
+    @{ ok = $false; reason = "image size mismatch"; changedGreenPixels = 0 } | ConvertTo-Json -Compress
+    exit 0
+  }
+  $left = [int]($after.Width * 0.52)
+  $right = [int]($after.Width * 0.96)
+  $top = [int]($after.Height * ${Number(detector.topRatio)})
+  $bottom = [int]($after.Height * ${Number(detector.bottomRatio)})
+  $changedPixels = 0
+  $minX = $after.Width
+  $minY = $after.Height
+  $maxX = 0
+  $maxY = 0
+  for ($y = $top; $y -lt $bottom; $y += 2) {
+    for ($x = $left; $x -lt $right; $x += 2) {
+      $a = $after.GetPixel($x, $y)
+      $b = $before.GetPixel($x, $y)
+      $isGreen = $a.G -ge 175 -and $a.R -ge 80 -and $a.R -le 190 -and $a.B -ge 50 -and $a.B -le 180 -and ($a.G - $a.R) -ge 25 -and ($a.G - $a.B) -ge 45
+      $isNonBackground = -not ($a.R -ge 245 -and $a.G -ge 245 -and $a.B -ge 245) -and -not ($a.R -ge 235 -and $a.G -ge 235 -and $a.B -ge 235 -and [Math]::Abs($a.R - $a.G) -le 5 -and [Math]::Abs($a.G - $a.B) -le 5)
+      $changed = ([Math]::Abs($a.R - $b.R) + [Math]::Abs($a.G - $b.G) + [Math]::Abs($a.B - $b.B)) -ge 45
+      $wanted = ${detector.predicate === 'green' ? '$isGreen' : '$isNonBackground'}
+      if ($wanted -and $changed) {
+        $changedPixels += 1
+        if ($x -lt $minX) { $minX = $x }
+        if ($y -lt $minY) { $minY = $y }
+        if ($x -gt $maxX) { $maxX = $x }
+        if ($y -gt $maxY) { $maxY = $y }
+      }
+    }
+  }
+  @{
+    ok = $changedPixels -ge ${Number(detector.minimumPixels)}
+    kind = "${psSingleQuoted(detector.kind)}"
+    changedPixels = $changedPixels
+    sampledStep = 2
+    box = @{ x = $minX; y = $minY; width = [Math]::Max(0, $maxX - $minX); height = [Math]::Max(0, $maxY - $minY) }
+  } | ConvertTo-Json -Depth 4 -Compress
+} finally {
+  $before.Dispose()
+  $after.Dispose()
+}
+`
+  const encoded = Buffer.from(script, 'utf16le').toString('base64')
+  const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded], {
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  let stdout = ''
+  let stderr = ''
+  child.stdout.setEncoding('utf8')
+  child.stderr.setEncoding('utf8')
+  child.stdout.on('data', chunk => { stdout += chunk })
+  child.stderr.on('data', chunk => { stderr += chunk })
+  const exitCode = await new Promise((resolve, reject) => {
+    child.on('error', reject)
+    child.on('close', resolve)
+  })
+  if (exitCode !== 0) return { ok: false, reason: stderr.trim() || `powershell exited ${exitCode}` }
+  try {
+    return JSON.parse(stdout.trim())
+  } catch {
+    return { ok: false, reason: stdout.trim() || 'invalid bubble detector JSON' }
+  }
+}
+
+export function summarizeObservations(observations, limit) {
   return (Array.isArray(observations) ? observations : [])
     .filter(row => observationText(row))
+    .filter(isUsefulSummaryObservation)
+    .sort((a, b) => observationBottom(a) - observationBottom(b))
     .slice(-limit)
     .map(row => ({
       text: observationText(row),
@@ -337,6 +783,23 @@ function summarizeObservations(observations, limit) {
     }))
 }
 
+function observationBottom(row) {
+  const box = row?.box || row
+  return Number(box?.y || 0) + Number(box?.height || 0)
+}
+
+function isUsefulSummaryObservation(row) {
+  const text = observationText(row)
+  const compact = normalizedMessageText(text)
+  if (!compact) return false
+  if (/^[0-9:：.\-]+$/.test(compact)) return false
+  if (/^[0-9]{1,2}[a-z\u0400-\u04ff]{1,3}[0-9]{1,2}$/i.test(compact)) return false
+  if (/^[0-9].*[0-9]$/.test(compact) && compact.length <= 8) return false
+  if (compact.replace(/^[0０]+/, '') === normalizedMessageText('微信电脑版')) return false
+  if (compact === '0') return false
+  return compact.length >= 2 || Boolean(row?.attachment)
+}
+
 function normalizedMessageText(value) {
   return String(value || '').replace(/\s+/g, '').toLowerCase()
 }
@@ -346,10 +809,139 @@ export function observationsContainText(observations, text) {
   if (!target) return true
   return (Array.isArray(observations) ? observations : []).some(row => {
     const content = normalizedMessageText(observationText(row))
-    return content.includes(target) || target.includes(content)
+    return isStrongTextMatch(content, target)
   })
 }
 
+export function findSentTextConfirmation(observations, text) {
+  const target = normalizedMessageText(text)
+  if (!target) return null
+  return (Array.isArray(observations) ? observations : []).find(row => {
+    const content = normalizedMessageText(observationText(row))
+    return isStrongTextMatch(content, target) && isLikelyOutboundMessageText(row)
+  }) || null
+}
+
+async function confirmSentText(confirmOcr, text, beforeCapture, afterCapture) {
+  const ocrHit = findSentTextConfirmation(confirmOcr.observations, text)
+  if (ocrHit) return { method: 'ocr-outbound-text', observation: ocrHit }
+
+  const visual = await detectNewOutboundBubble(beforeCapture?.file, afterCapture?.file)
+  if (visual?.ok) {
+    return {
+      method: 'visual-new-outbound-bubble',
+      observation: {
+        text,
+        role: 'outbound-visual',
+        confidence: 0,
+        box: visual.box,
+        visual,
+      },
+    }
+  }
+
+  return { method: 'none', visual }
+}
+
+async function assertComposerEmptyBeforeSend(options, artifacts) {
+  const composerCapture = await capture('window', options, 'composer-before-send')
+  artifacts.push(composerCapture.file)
+  const composerOcr = await recognizeScreenshot(composerCapture, options, 'composer-before-send')
+  const dirtyObservation = findComposerDirtyObservation(composerOcr.observations)
+  const dirtyVisual = dirtyObservation ? null : await detectComposerPendingAttachmentVisual(composerCapture.file)
+  if (dirtyObservation || dirtyVisual?.ok) {
+    writeJsonArtifact(options, 'composer-before-send-ocr.json', {
+      ocrEvidence: summarizeOcrEvidence(composerOcr),
+      dirtyObservation,
+      dirtyVisual,
+      sample: summarizeObservations(composerOcr.observations, 20),
+    })
+    throw new Error(
+      'WeChat composer is not empty before send; pending text or attachments are already staged. ' +
+      `Refusing to paste/send new content. See ${composerCapture.file}`,
+    )
+  }
+  return { capture: composerCapture, ocr: composerOcr }
+}
+
+function isLikelyOutboundMessageText(row) {
+  const box = row?.box || row
+  if (!box) return false
+  const x = Number(box.x || 0)
+  const y = Number(box.y || 0)
+  const width = Number(box.width || 0)
+  const height = Number(box.height || 0)
+  const normalized = Math.max(Math.abs(x), Math.abs(y), Math.abs(width), Math.abs(height)) <= 1
+  const centerX = x + width / 2
+  const centerY = y + height / 2
+  if (normalized) return centerX >= 0.52 && centerY >= 0.22 && centerY <= 0.88
+  return centerX >= 700 && centerY >= 180 && centerY <= 900
+}
+
+function isLikelyComposerSendButton(row) {
+  const box = row?.box || row
+  if (!box) return false
+  const x = Number(box.x || 0)
+  const y = Number(box.y || 0)
+  const width = Number(box.width || 0)
+  const height = Number(box.height || 0)
+  const normalized = Math.max(Math.abs(x), Math.abs(y), Math.abs(width), Math.abs(height)) <= 1
+  const centerX = x + width / 2
+  const centerY = y + height / 2
+  if (normalized) return centerX >= 0.78 && centerY >= 0.82
+  return centerX >= 900 && centerY >= 720
+}
+
+function normalizedObservationCenter(row) {
+  const box = row?.box || row
+  if (!box) return null
+  const x = Number(box.x || 0)
+  const y = Number(box.y || 0)
+  const width = Number(box.width || 0)
+  const height = Number(box.height || 0)
+  const centerX = x + width / 2
+  const centerY = y + height / 2
+  const normalized = Math.max(Math.abs(x), Math.abs(y), Math.abs(width), Math.abs(height)) <= 1
+  if (normalized) return { x: centerX, y: centerY }
+  const imageWidth = Number(row?.imageWidth || box.imageWidth || 0)
+  const imageHeight = Number(row?.imageHeight || box.imageHeight || 0)
+  if (imageWidth > 0 && imageHeight > 0) return { x: centerX / imageWidth, y: centerY / imageHeight }
+  return { x: centerX / 1800, y: centerY / 1100 }
+}
+
+function looksLikeComposerPendingAttachmentText(value) {
+  const text = normalizedMessageText(value)
+    .replace(/[．。]/g, '.')
+    .replace(/[｜|]/g, 'i')
+  return /\.(txt|csv|pdf|docx?|xlsx?|pptx?|zip|rar|7z|png|jpe?g|gif|webp|bmp|mp4|mov|avi|mkv|webm)$/i.test(text) ||
+    /\.(txt|csv|pdf|docx?|xlsx?|pptx?|zip|rar|7z|png|jpe?g|gif|webp|bmp|mp4|mov|avi|mkv|webm)\b/i.test(text)
+}
+
+function isLikelyComposerPendingAttachment(row) {
+  const center = normalizedObservationCenter(row)
+  if (!center) return false
+  return center.x >= 0.26 && center.x <= 0.86 && center.y >= 0.78
+}
+
+function isLikelyMainTitle(row) {
+  const box = row?.box || row
+  if (!box) return false
+  const x = Number(box.x || 0)
+  const y = Number(box.y || 0)
+  const width = Number(box.width || 0)
+  const height = Number(box.height || 0)
+  const normalized = Math.max(Math.abs(x), Math.abs(y), Math.abs(width), Math.abs(height)) <= 1
+  if (normalized) return x >= 0.32 && y <= 0.18
+  return x >= 360 && y <= 160
+}
+
+function isStrongTextMatch(content, target) {
+  if (!content || !target) return false
+  if (content.includes(target)) return true
+  const minimumReverseLength = Math.min(8, Math.max(4, Math.ceil(target.length * 0.5)))
+  return content.length >= minimumReverseLength && target.includes(content)
+}
+
 function basenameForAnyPlatform(file) {
   const value = String(file || '')
   return value.includes('\\') ? path.win32.basename(value) : path.basename(value)
@@ -390,6 +982,29 @@ function mimeTypeFromExt(ext) {
   return 'application/octet-stream'
 }
 
+function attachmentFromText(text) {
+  const normalized = normalizeFileCardText(text)
+  const match = normalized.match(/[a-z0-9][a-z0-9._-]{2,}\.(txt|pdf|docx?|xlsx?|pptx?|zip|rar|7z|png|jpe?g|gif|webp|mp4|mov|avi|mkv|webm)\b/i)
+  if (!match) return null
+  const name = safeFileName(match[0])
+  const ext = path.extname(name).toLowerCase()
+  return {
+    type: attachmentTypeFromExt(ext),
+    name,
+    mimeType: mimeTypeFromExt(ext),
+    availability: 'remote',
+  }
+}
+
+function normalizeFileCardText(text) {
+  return String(text || '')
+    .normalize('NFKC')
+    .replace(/w[l1i]n/gi, 'win')
+    .replace(/[一－—–]/g, '-')
+    .replace(/[．。·]/g, '.')
+    .replace(/\s+/g, '')
+}
+
 function attachmentTypeFromExt(ext) {
   if (IMAGE_EXTENSIONS.has(String(ext || '').toLowerCase())) return 'image'
   if (VIDEO_EXTENSIONS.has(String(ext || '').toLowerCase())) return 'video'
@@ -418,73 +1033,241 @@ export function classifyOutboundFile(file) {
   }
 }
 
-function candidateDownloadRoots() {
-  const home = process.env.USERPROFILE || process.env.HOME || ''
-  return [
-    process.env.USERPROFILE ? path.win32.join(process.env.USERPROFILE, 'Downloads') : '',
-    process.env.USERPROFILE ? path.win32.join(process.env.USERPROFILE, 'Documents') : '',
-    process.env.USERPROFILE ? path.win32.join(process.env.USERPROFILE, 'Desktop') : '',
-    process.env.USERPROFILE ? path.win32.join(process.env.USERPROFILE, 'Documents', 'WeChat Files') : '',
-    home && !process.env.USERPROFILE ? path.join(home, 'Downloads') : '',
-  ].filter((root, index, roots) => root && roots.indexOf(root) === index && fs.existsSync(root))
+export function copyInboundAttachment(source, targetDir, attachment) {
+  const buffer = fs.readFileSync(source.path)
+  const hash = crypto.createHash('sha256').update(buffer).digest('hex')
+  const sourceName = path.basename(source.path)
+  const preferredName = attachment?.name && /\.[\p{L}\p{N}]+$/u.test(attachment.name) ? attachment.name : sourceName
+  const filePath = uniqueInboundPath(targetDir, preferredName, hash)
+  fs.mkdirSync(targetDir, { recursive: true })
+  if (!fs.existsSync(filePath)) fs.writeFileSync(filePath, buffer)
+  const ext = path.extname(filePath).toLowerCase()
+  return {
+    type: attachment?.type || attachmentTypeFromExt(ext),
+    name: path.basename(filePath),
+    mimeType: attachment?.mimeType || mimeTypeFromExt(ext),
+    size: buffer.byteLength,
+    localPath: filePath,
+    hash,
+    availability: 'edge-local',
+  }
 }
 
-function walkFiles(root, maxDepth, limit) {
-  const result = []
-  const stack = [{ dir: root, depth: 0 }]
-  while (stack.length && result.length < limit) {
+export function summarizeAttachmentObservations(observations, limit) {
+  return (Array.isArray(observations) ? observations : [])
+    .filter(row => row?.box && observationText(row))
+    .map(row => {
+      const attachment = row.attachment || attachmentFromText(observationText(row)) || attachmentFromSizeRow(row)
+      if (!attachment) return null
+      return {
+        text: observationText(row) || attachment.name,
+        role: row.role || 'unknown',
+        confidence: observationConfidence(row),
+        box: row.box,
+        attachment,
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => observationBottom(a) - observationBottom(b))
+    .slice(-limit)
+}
+
+function attachmentFromSizeRow(row) {
+  const text = normalizedMessageText(observationText(row)).replace(/,/g, '')
+  const box = row?.box || row
+  const x = Number(box?.x || 0)
+  if (!/^\d+(?:\.\d+)?(?:b|kb|mb|gb)$/.test(text)) return null
+  if (x < 260) return null
+  return {
+    type: 'file',
+    name: 'wechat-attachment',
+    mimeType: 'application/octet-stream',
+    availability: 'remote',
+  }
+}
+
+function mergeRecentMessagesWithAttachments(recentMessages, attachmentMessages, limit) {
+  const merged = [...recentMessages]
+  for (const message of attachmentMessages) {
+    const existingIndex = merged.findIndex(item => item.attachment?.name === message.attachment?.name || (
+      item.box && message.box && Math.abs(observationBottom(item) - observationBottom(message)) < 8
+    ))
+    if (existingIndex >= 0) {
+      if (!merged[existingIndex].attachment && message.attachment) merged[existingIndex] = { ...merged[existingIndex], attachment: message.attachment }
+    } else {
+      merged.push(message)
+    }
+  }
+  return merged
+    .sort((a, b) => observationBottom(a) - observationBottom(b))
+    .slice(-limit)
+}
+
+function clipboardSourceFile(payload) {
+  const files = Array.isArray(payload?.files) ? payload.files : Array.isArray(payload?.Files) ? payload.Files : []
+  for (const file of files) {
+    const candidate = String(file || '').trim()
+    if (candidate && fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return { path: candidate, size: fs.statSync(candidate).size, mtimeMs: fs.statSync(candidate).mtimeMs }
+    }
+  }
+
+  const text = String(payload?.text || payload?.Text || '')
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim().replace(/^["']|["']$/g, '')
+    const candidate = line.startsWith('file:///') ? decodeURIComponent(line.replace(/^file:\/\/\//i, '')) : line
+    if (candidate && fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return { path: candidate, size: fs.statSync(candidate).size, mtimeMs: fs.statSync(candidate).mtimeMs }
+    }
+  }
+
+  return null
+}
+
+function defaultWeChatCacheRoots() {
+  const roots = []
+  const home = process.env.USERPROFILE || process.env.HOME
+  if (home) {
+    roots.push(path.join(home, 'Documents', 'xwechat_files'))
+    roots.push(path.join(home, 'Documents', 'WeChat Files'))
+  }
+  return roots
+}
+
+function extensionForAttachment(attachment = {}, options = {}) {
+  const name = String(attachment.name || '')
+  const ext = path.extname(name).toLowerCase()
+  if (ext) return ext
+  for (const token of Array.isArray(options.downloadExpectedTokens) ? options.downloadExpectedTokens : []) {
+    const tokenExt = path.extname(String(token || '')).toLowerCase()
+    if (tokenExt) return tokenExt
+  }
+  const mime = String(attachment.mimeType || '').toLowerCase()
+  if (mime === 'image/png') return '.png'
+  if (mime === 'image/jpeg') return '.jpg'
+  if (mime === 'image/gif') return '.gif'
+  if (mime === 'application/pdf') return '.pdf'
+  if (mime.includes('mp4')) return '.mp4'
+  return ''
+}
+
+function cacheLookupTokens(message = {}, attachment = {}, options = {}) {
+  const values = [
+    message.text,
+    attachment.name,
+    ...(Array.isArray(options.downloadExpectedTokens) ? options.downloadExpectedTokens : []),
+  ].map(value => normalizedFileNameToken(value)).filter(Boolean)
+  const tokens = new Set()
+  for (const value of values) {
+    for (const token of value.split(/[^a-z0-9]+/i)) {
+      if (token.length >= 4 && !/^(file|image|video|pdf|png|jpg|jpeg|mp4)$/i.test(token)) {
+        tokens.add(token.toLowerCase())
+      }
+    }
+    if (value.length >= 8) tokens.add(value.toLowerCase())
+  }
+  return [...tokens]
+}
+
+export function expectedDownloadTokenMessages(options = {}) {
+  return (Array.isArray(options.downloadExpectedTokens) ? options.downloadExpectedTokens : [])
+    .map((token) => {
+      const name = safeFileName(basenameForAnyPlatform(token))
+      const ext = path.extname(name).toLowerCase()
+      if (!ext) return null
+      return {
+        text: name,
+        role: 'expected-download-token',
+        confidence: 0,
+        attachment: {
+          type: attachmentTypeFromExt(ext),
+          name,
+          mimeType: mimeTypeFromExt(ext),
+          availability: 'remote',
+        },
+      }
+    })
+    .filter(Boolean)
+}
+
+function candidateCacheFiles(roots, options = {}) {
+  const maxFiles = Number(options.maxCacheFiles || 5000)
+  const minMtimeMs = Date.now() - Number(options.maxCacheAgeMs || 14 * 24 * 60 * 60 * 1000)
+  const files = []
+  const stack = roots.filter(Boolean).map(root => path.resolve(root))
+  const seen = new Set()
+  while (stack.length && files.length < maxFiles) {
     const current = stack.pop()
+    if (!current || seen.has(current)) continue
+    seen.add(current)
     let entries = []
     try {
-      entries = fs.readdirSync(current.dir, { withFileTypes: true })
+      entries = fs.readdirSync(current, { withFileTypes: true })
     } catch {
       continue
     }
     for (const entry of entries) {
-      const filePath = path.join(current.dir, entry.name)
+      const fullPath = path.join(current, entry.name)
       if (entry.isDirectory()) {
-        if (current.depth < maxDepth) stack.push({ dir: filePath, depth: current.depth + 1 })
+        if (/^(cache|temp|rwtemp|filestorage|msgattach|image|video|file|[0-9-]+)$/i.test(entry.name) || current.toLowerCase().includes('xwechat_files')) {
+          stack.push(fullPath)
+        }
         continue
       }
       if (!entry.isFile()) continue
+      let stat
       try {
-        const stat = fs.statSync(filePath)
-        result.push({ path: filePath, size: stat.size, mtimeMs: stat.mtimeMs })
+        stat = fs.statSync(fullPath)
       } catch {
-        // Ignore transient files while WeChat is writing them.
+        continue
       }
+      if (stat.mtimeMs < minMtimeMs || stat.size <= 0) continue
+      files.push({ path: fullPath, size: stat.size, mtimeMs: stat.mtimeMs, name: entry.name })
+      if (files.length >= maxFiles) break
     }
   }
-  return result
+  return files.sort((a, b) => b.mtimeMs - a.mtimeMs)
 }
 
-function snapshotDownloadCandidates() {
-  const files = new Map()
-  for (const root of candidateDownloadRoots()) {
-    for (const file of walkFiles(root, 4, 5000)) {
-      files.set(file.path, file)
-    }
-  }
-  return files
+export function findCachedInboundAttachment(message = {}, attachment = {}, options = {}) {
+  const ext = extensionForAttachment(attachment, options)
+  const tokens = cacheLookupTokens(message, attachment, options)
+  const roots = options.wechatCacheRoots || defaultWeChatCacheRoots()
+  if (!ext || tokens.length === 0 || roots.length === 0) return null
+  const candidates = candidateCacheFiles(roots, options)
+    .filter(file => path.extname(file.name).toLowerCase() === ext)
+    .map(file => {
+      const normalizedName = normalizedFileNameToken(file.name)
+      const score = tokens.reduce((sum, token) => sum + (normalizedName.includes(token) ? Math.min(20, token.length) : 0), 0)
+      return { ...file, score }
+    })
+    .filter(file => file.score > 0)
+    .sort((a, b) => b.score - a.score || b.mtimeMs - a.mtimeMs)
+  const best = candidates[0]
+  return best ? { path: best.path, size: best.size, mtimeMs: best.mtimeMs } : null
 }
 
-export function copyInboundAttachment(source, targetDir, attachment) {
-  const buffer = fs.readFileSync(source.path)
-  const hash = crypto.createHash('sha256').update(buffer).digest('hex')
-  const sourceName = path.basename(source.path)
-  const preferredName = attachment?.name && /\.[\p{L}\p{N}]+$/u.test(attachment.name) ? attachment.name : sourceName
-  const filePath = uniqueInboundPath(targetDir, preferredName, hash)
-  fs.mkdirSync(targetDir, { recursive: true })
-  if (!fs.existsSync(filePath)) fs.writeFileSync(filePath, buffer)
-  const ext = path.extname(filePath).toLowerCase()
+export function findCopyMenuItem(observations) {
+  const rows = (Array.isArray(observations) ? observations : [])
+    .filter(row => row?.box && observationText(row))
+    .map(row => ({ row, text: normalizeText(observationText(row)).toLowerCase() }))
+  return rows.find(({ text }) => /^(复制|拷贝|copy)$/i.test(text))?.row
+    || rows.find(({ text }) => /复制|拷贝|\bcopy\b/i.test(text))?.row
+    || null
+}
+
+function attachmentRightClickPoint(capturePayload, message, imageSize) {
+  const point = pointFromObservation(capturePayload, message, imageSize)
+  const box = message?.box || {}
+  const text = normalizedMessageText(observationText(message)).replace(/,/g, '')
+  const isSizeOnly = /^\d+(?:\.\d+)?(?:b|kb|mb|gb)$/.test(text)
+  if (!isSizeOnly) return point
+
+  const scale = imageSize?.width && Number(box.x || 0) <= 1 && Number(box.width || 0) <= 1 ? imageSize.width : 1
+  const width = Number(box.width || 0) * scale
   return {
-    type: attachment?.type || attachmentTypeFromExt(ext),
-    name: path.basename(filePath),
-    mimeType: attachment?.mimeType || mimeTypeFromExt(ext),
-    size: buffer.byteLength,
-    localPath: filePath,
-    hash,
-    availability: 'edge-local',
+    x: Math.round(point.x + Math.max(48, Math.min(140, width + 72))),
+    y: Math.round(point.y - 18),
   }
 }
 
@@ -494,66 +1277,197 @@ async function localizeInboundAttachments(recentMessages, messageCapture, option
   }
   const targetDir = path.resolve(options.downloadAttachmentsDir)
   fs.mkdirSync(targetDir, { recursive: true })
-  let before = snapshotDownloadCandidates()
+  const maxDownloads = downloadAttachmentLimit(options)
   const downloads = []
   const updated = []
-  for (const message of recentMessages) {
+  const messages = [...recentMessages]
+  for (const expected of expectedDownloadTokenMessages(options)) {
+    const exists = messages.some(message => message?.attachment?.name === expected.attachment.name)
+    if (!exists) messages.push(expected)
+  }
+  for (const message of messages) {
+    if (downloads.length >= maxDownloads) {
+      updated.push(message)
+      continue
+    }
     const attachment = message.attachment
-    if (!attachment || attachment.localPath || attachment.url || !message.box) {
+    if (!attachment || attachment.localPath || attachment.url) {
       updated.push(message)
       continue
     }
-    const startedAt = Date.now()
-    await click(pointFromObservation(messageCapture.payload, message, messageCapture.imageSize), options, ['--no-raise'])
-    await sleep(2_000)
-    await press('{ESC}', options).catch(() => {})
-    const downloaded = selectDownloadedAttachment(before, snapshotDownloadCandidates(), startedAt, attachment)
-    if (!downloaded) {
+    const cached = findCachedInboundAttachment(message, attachment, options)
+    if (cached) {
+      const localized = copyInboundAttachment(cached, targetDir, attachment)
+      updated.push({ ...message, text: message.text || localized.name, attachment: localized })
+      downloads.push({ text: message.text, ok: true, strategy: 'wechat-cache-scan', sourcePath: cached.path, localPath: localized.localPath, size: localized.size })
+      continue
+    }
+    if (!options.allowRightClickDownload) {
+      const pending = {
+        ...message,
+        attachment: {
+          ...attachment,
+          availability: 'pending-download',
+          providerError: 'No matching local WeChat cache file found; right-click download fallback is disabled on Windows.',
+        },
+      }
+      updated.push(pending)
+      downloads.push({ text: message.text, ok: false, strategy: 'wechat-cache-scan', providerError: pending.attachment.providerError })
+      continue
+    }
+    if (!message.box) {
       const pending = {
         ...message,
         attachment: {
           ...attachment,
           availability: 'pending-download',
-          providerError: 'No new downloaded file was observed after clicking attachment bubble',
+          providerError: 'Right-click download fallback requires an OCR box, but cache-only lookup did not find a local file.',
+        },
+      }
+      updated.push(pending)
+      downloads.push({ text: message.text, ok: false, strategy: 'right-click-copy', providerError: pending.attachment.providerError })
+      continue
+    }
+    const targetPoint = attachmentRightClickPoint(messageCapture.payload, message, messageCapture.imageSize)
+    writeDebugArtifact(options, `download-attachment-${downloads.length + 1}-target.json`, {
+      text: message.text,
+      box: message.box,
+      point: targetPoint,
+      strategy: 'right-click-copy',
+    })
+    await rightClick(targetPoint, options, ['--no-raise'])
+    await sleep(350)
+
+    let copied = null
+    let providerError = ''
+    try {
+      const menuCapture = await capture('window', options, `context-menu-${downloads.length + 1}`)
+      const menuOcr = await recognizeScreenshot(menuCapture, options, 'context-menu')
+      writeDebugArtifact(options, `download-attachment-${downloads.length + 1}-menu.json`, menuOcr.observations)
+      const copyItem = findCopyMenuItem(menuOcr.observations)
+      if (!copyItem) {
+        providerError = 'Right-click attachment menu did not expose a Copy item'
+      } else {
+        await click(pointFromObservation(menuCapture.payload, copyItem, menuCapture.imageSize), options, ['--no-raise'])
+        await sleep(350)
+        const clipboard = await readClipboard(options)
+        writeDebugArtifact(options, `download-attachment-${downloads.length + 1}-clipboard.json`, clipboard)
+        copied = clipboardSourceFile(clipboard)
+        if (!copied) providerError = 'Right-click Copy did not put a local file path on the clipboard'
+      }
+    } finally {
+      await dismissMenus(options, 2).catch(() => {})
+      await press('{ESC}', options).catch(() => {})
+    }
+
+    if (!copied) {
+      const pending = {
+        ...message,
+        attachment: {
+          ...attachment,
+          availability: 'pending-download',
+          providerError,
         },
       }
       updated.push(pending)
       downloads.push({ text: message.text, ok: false, providerError: pending.attachment.providerError })
-      before = snapshotDownloadCandidates()
       continue
     }
-    const localized = copyInboundAttachment(downloaded, targetDir, attachment)
+    const localized = copyInboundAttachment(copied, targetDir, attachment)
     updated.push({ ...message, text: message.text || localized.name, attachment: localized })
-    downloads.push({ text: message.text, ok: true, sourcePath: downloaded.path, localPath: localized.localPath, size: localized.size })
-    before = snapshotDownloadCandidates()
+    downloads.push({ text: message.text, ok: true, sourcePath: copied.path, localPath: localized.localPath, size: localized.size })
   }
   return { recentMessages: updated, downloads }
 }
 
+export function downloadAttachmentLimit(options = {}) {
+  const value = Number(options.downloadLimit ?? 1)
+  if (!Number.isFinite(value) || value < 1) return 1
+  // Windows WeChat can lose its enumerable main window after repeated
+  // right-click attachment menus. Keep live runs to one attachment until this
+  // path has a separate stability gate.
+  return Math.min(1, Math.floor(value))
+}
+
 export function missingConfirmedFiles(observations, files) {
   const rows = Array.isArray(observations) ? observations : []
+  const combinedText = normalizedMessageText(rows.map(row => observationText(row)).join(''))
+  const combinedFileToken = normalizedFileNameToken(rows.map(row => observationText(row)).join(''))
   return (files || []).filter(file => {
     const basename = basenameForAnyPlatform(file)
     const normalizedBasename = normalizedMessageText(basename)
+    const normalizedFileToken = normalizedFileNameToken(basename)
+    if (combinedText.includes(normalizedBasename)) return false
+    if (normalizedFileToken && combinedFileToken.includes(normalizedFileToken)) return false
     return !rows.some(row => {
       const text = normalizedMessageText(observationText(row))
       const attachmentName = normalizedMessageText(row?.attachment?.filename || row?.attachment?.name)
-      return text.includes(normalizedBasename) || attachmentName.includes(normalizedBasename)
+      const fileText = normalizedFileNameToken(observationText(row))
+      const fileAttachmentName = normalizedFileNameToken(row?.attachment?.filename || row?.attachment?.name)
+      return text.includes(normalizedBasename)
+        || attachmentName.includes(normalizedBasename)
+        || (normalizedFileToken && fileText.includes(normalizedFileToken))
+        || (normalizedFileToken && fileAttachmentName.includes(normalizedFileToken))
     })
   })
 }
 
+function normalizedFileNameToken(value) {
+  return String(value || '')
+    .normalize('NFKC')
+    .toLowerCase()
+    .replace(/w[l1i]n/g, 'win')
+    .replace(/[\s._\-—–一．。·,，:：;；/\\|[\]()（）{}<>《》"'“”‘’]+/g, '')
+    .replace(/[^a-z0-9\u4e00-\u9fff]+/g, '')
+}
+
 async function openConversationBySearch(options, artifacts) {
   const initial = await capture('window', options, 'window-before-search')
   artifacts.push(initial.file)
   try {
     const initialTitleOcr = await recognizeScreenshot(initial, options, 'title-confirmation')
     if (findTitleConfirmation(initialTitleOcr.observations, options.group)) {
+      initial.openEvidence = {
+        strategy: 'current-title',
+        searchUsed: false,
+        leftListUsed: false,
+        titleConfirmed: true,
+      }
       return initial
     }
   } catch (error) {
     process.stderr.write(`Initial title OCR was skipped: ${error instanceof Error ? error.message : String(error)}\n`)
   }
+  const initialOcr = await recognizeScreenshot(initial, options, 'left-list')
+  const leftListTarget = findConversationInLeftList(initialOcr.observations, options.group)
+  if (leftListTarget) {
+    const targetPoint = pointFromObservation(initial.payload, leftListTarget, initial.imageSize)
+    writeDebugArtifact(options, 'open-target-left-list.json', {
+      group: options.group,
+      text: observationText(leftListTarget),
+      box: leftListTarget.box,
+      point: targetPoint,
+    })
+    await click(targetPoint, options, ['--no-raise'])
+    await sleep(650)
+    const opened = await waitForStableWindow(options, 'opened-from-left-list', { attempts: 6, delayMs: 800 })
+    artifacts.push(opened.file)
+    const titleOcr = await recognizeScreenshot(opened, options, 'title-confirmation')
+    const titleConfirmed = Boolean(findTitleConfirmation(titleOcr.observations, options.group))
+    if (!titleConfirmed) {
+      if (!options.allowWeakTitle) throw new Error(`Opened left-list conversation title was not confirmed as '${options.group}'. See ${opened.file}`)
+    }
+    opened.openEvidence = {
+      strategy: 'left-list',
+      searchUsed: false,
+      leftListUsed: true,
+      titleConfirmed,
+      targetText: observationText(leftListTarget),
+    }
+    return opened
+  }
+
+  assertSearchOpenAllowed(options, options.group)
 
   await click(geometryPoint(initial.payload, 'search'), options)
   await sleep(180)
@@ -569,6 +1483,12 @@ async function openConversationBySearch(options, artifacts) {
     throw new Error(`Could not find target group '${options.group}' under search result section '群聊'. See ${searchCapture.file}`)
   }
   const targetPoint = pointFromObservation(searchCapture.payload, target, searchCapture.imageSize)
+  writeDebugArtifact(options, 'open-target-search.json', {
+    group: options.group,
+    text: observationText(target),
+    box: target.box,
+    point: targetPoint,
+  })
   await click(targetPoint, options, ['--no-raise'])
   await sleep(350)
   // WeChat 4.x can keep the transient search result panel open after clicking a result.
@@ -576,25 +1496,68 @@ async function openConversationBySearch(options, artifacts) {
   await press('{ESC}', options)
   await sleep(500)
 
-  const opened = await capture('window', options, 'opened-conversation')
+  const opened = await waitForStableWindow(options, 'opened-conversation', { attempts: 6, delayMs: 800 })
   artifacts.push(opened.file)
   const titleOcr = await recognizeScreenshot(opened, options, 'title-confirmation')
-  if (!findTitleConfirmation(titleOcr.observations, options.group)) {
+  const titleConfirmed = Boolean(findTitleConfirmation(titleOcr.observations, options.group))
+  if (!titleConfirmed) {
     // Some OCR models miss the top title but the click may still be correct. Keep the debug capture and continue
     // only if the caller explicitly opted out of strict confirmation.
     if (!options.allowWeakTitle) throw new Error(`Opened conversation title was not confirmed as '${options.group}'. See ${opened.file}`)
   }
+  opened.openEvidence = {
+    strategy: 'search',
+    searchUsed: true,
+    leftListUsed: false,
+    titleConfirmed,
+    targetText: observationText(target),
+  }
   return opened
 }
 
+export function buildActionEvidence({ options = {}, opened = {}, sent = [], downloads = [], postRunSafety = {}, artifacts = [], layout = {} } = {}) {
+  const confirmationMethods = []
+  for (const item of Array.isArray(sent) ? sent : []) {
+    if (item?.confirmationMethod) confirmationMethods.push(item.confirmationMethod)
+    if (Array.isArray(item?.confirmationMethods)) confirmationMethods.push(...item.confirmationMethods)
+  }
+  const downloadStrategies = Array.from(new Set((Array.isArray(downloads) ? downloads : [])
+    .map(item => item?.strategy)
+    .filter(Boolean)))
+  const openEvidence = opened?.openEvidence || {}
+  return {
+    targetGroup: options.group || '',
+    openStrategy: openEvidence.strategy || 'unknown',
+    searchUsed: Boolean(openEvidence.searchUsed),
+    leftListUsed: Boolean(openEvidence.leftListUsed),
+    titleConfirmed: Boolean(openEvidence.titleConfirmed),
+    searchOpenAllowed: Boolean(options.allowSearchOpen),
+    rightClickDownloadAllowed: Boolean(options.allowRightClickDownload),
+    rightClickUsed: downloadStrategies.includes('right-click-copy'),
+    downloadStrategies,
+    sentTypes: (Array.isArray(sent) ? sent : []).map(item => item?.type).filter(Boolean),
+    confirmationMethods: Array.from(new Set(confirmationMethods)),
+    postRunSafetyOk: postRunSafety?.ok === true,
+    postRunSafetyArtifact: postRunSafety?.artifact || '',
+    artifactCount: Array.isArray(artifacts) ? artifacts.length : 0,
+    layout: {
+      currentTitle: layout?.currentTitle || '',
+      messageCount: Number(layout?.messageCount || 0),
+      attachmentCount: Number(layout?.attachmentCount || 0),
+      hasInputBox: Boolean(layout?.inputBox),
+      hasMessageArea: Boolean(layout?.messageArea),
+    },
+  }
+}
+
 export async function runVisualFlow(input) {
   const captureDir = path.resolve(input.captureDir || fs.mkdtempSync(path.join(fs.realpathSync(process.env.TEMP || process.env.TMP || '/tmp'), 'shennian-wechat-rpa-win-visual-')))
-  fs.mkdirSync(captureDir, { recursive: true })
+  prepareCaptureDir(captureDir)
   const options = {
     ...input,
     captureDir,
     step: 1,
-    recentLimit: Number(input.recentLimit || 5),
+    recentLimit: Math.max(Number(input.recentLimit || 5), input.downloadAttachmentsDir && input.downloadAttachments !== false ? 20 : 0),
     ocrTimeoutMs: Number(input.ocrTimeoutMs || 45_000),
     openTimeoutMs: Number(input.openTimeoutMs || 12_000),
   }
@@ -606,10 +1569,18 @@ export async function runVisualFlow(input) {
   artifacts.push(messageCapture.file)
   const messageOcr = await recognizeScreenshot(messageCapture, options, 'message-read')
   let recentMessages = summarizeObservations(messageOcr.observations, options.recentLimit)
+  recentMessages = mergeRecentMessagesWithAttachments(
+    recentMessages,
+    summarizeAttachmentObservations(messageOcr.observations, options.recentLimit),
+    options.recentLimit,
+  )
   const localization = await localizeInboundAttachments(recentMessages, messageCapture, options)
   recentMessages = localization.recentMessages
 
   const sent = []
+  if (!options.dryRun && (options.replyText || options.files?.length)) {
+    await assertComposerEmptyBeforeSend(options, artifacts)
+  }
   if (!options.dryRun && options.replyText) {
     await click(geometryPoint(opened.payload, 'input'), options)
     await pasteText(options.replyText, options)
@@ -619,52 +1590,105 @@ export async function runVisualFlow(input) {
     const confirmCapture = await capture('window', options, 'after-text-send')
     artifacts.push(confirmCapture.file)
     const confirmOcr = await recognizeScreenshot(confirmCapture, options, 'send-confirmation')
-    if (!observationsContainText(confirmOcr.observations, options.replyText)) {
-      throw new Error(`Sent text was not confirmed by OCR: '${options.replyText}'. See ${confirmCapture.file}`)
+    const confirmation = await confirmSentText(confirmOcr, options.replyText, opened, confirmCapture)
+    if (!confirmation.observation) {
+      throw new Error(`Sent text was not confirmed by OCR or outbound bubble diff: '${options.replyText}'. See ${confirmCapture.file}`)
     }
-    sent.push({ type: 'text', text: options.replyText, observations: summarizeObservations(confirmOcr.observations, options.recentLimit) })
+    sent.push({
+      type: 'text',
+      text: options.replyText,
+      confirmationMethod: confirmation.method,
+      observations: summarizeObservations([confirmation.observation], options.recentLimit),
+    })
   }
 
   if (!options.dryRun && options.files?.length) {
     const confirmedFiles = []
     const sentAttachments = []
     const confirmationObservations = []
+    const confirmationMethods = []
     for (const [index, file] of options.files.entries()) {
-      await click(geometryPoint(opened.payload, 'input'), options)
-      await pasteFiles([file], options)
-      await sleep(850)
-      const pendingCapture = await capture('input', options, `pending-file-${index + 1}`)
-      artifacts.push(pendingCapture.file)
-      await click(geometryPoint(opened.payload, 'send'), options)
+      let pendingCapture = null
+      let pendingOcr = null
+      let sendButton = null
+      for (let attempt = 1; attempt <= 2; attempt += 1) {
+        await click(geometryPoint(opened.payload, 'fileInput'), options)
+        await sleep(120)
+        await pasteFiles([file], options)
+        await sleep(950)
+        pendingCapture = await captureWithRetry('window', options, `pending-file-${index + 1}${attempt > 1 ? `-retry-${attempt}` : ''}`, { attempts: 8, delayMs: 900 })
+        artifacts.push(pendingCapture.file)
+        pendingOcr = await recognizeScreenshot(pendingCapture, options, 'send-button')
+        sendButton = findSendButtonObservation(pendingOcr.observations)
+        if (sendButton || missingConfirmedFiles(pendingOcr.observations, [file]).length === 0) break
+      }
+      if (!pendingCapture || !pendingOcr) throw new Error(`File was not captured after paste: ${basenameForAnyPlatform(file)}`)
+      if (!sendButton && missingConfirmedFiles(pendingOcr.observations, [file]).length > 0) {
+        throw new Error(`File did not appear in the WeChat composer after paste: ${basenameForAnyPlatform(file)}. See ${pendingCapture.file}`)
+      }
+      if (sendButton) {
+        await click(pointFromObservation(pendingCapture.payload, sendButton, pendingCapture.imageSize), options)
+      } else {
+        await press('{ENTER}', options)
+      }
       await sleep(postPasteDelayMs(file))
       const fileConfirmCapture = await capture('window', options, `after-file-${index + 1}-send`)
       artifacts.push(fileConfirmCapture.file)
       const fileConfirmOcr = await recognizeScreenshot(fileConfirmCapture, options, 'send-confirmation')
       const missing = missingConfirmedFiles(fileConfirmOcr.observations, [file])
       if (missing.length > 0) {
-        throw new Error(`Sent file was not confirmed by OCR: ${basenameForAnyPlatform(file)}. See ${fileConfirmCapture.file}`)
+        const visual = await detectNewOutboundAttachmentBubble(attachmentVisualBeforeFile(opened, pendingCapture), fileConfirmCapture.file)
+        if (!visual?.ok) {
+          throw new Error(`Sent file was not confirmed by OCR or outbound attachment diff: ${basenameForAnyPlatform(file)}. See ${fileConfirmCapture.file}`)
+        }
+        confirmationMethods.push('visual-new-outbound-attachment')
+        confirmationObservations.push({
+          text: basenameForAnyPlatform(file),
+          role: 'outbound-visual',
+          confidence: 0,
+          box: visual.box,
+          visual,
+        })
+      } else {
+        confirmationMethods.push('ocr-file-name')
+        confirmationObservations.push(...summarizeObservations(fileConfirmOcr.observations, options.recentLimit))
       }
       confirmedFiles.push(file)
       sentAttachments.push(classifyOutboundFile(file))
-      confirmationObservations.push(...summarizeObservations(fileConfirmOcr.observations, options.recentLimit))
     }
     sent.push({
       type: 'files',
       files: confirmedFiles,
+      confirmationMethods,
       attachments: sentAttachments,
       observations: confirmationObservations.slice(-options.recentLimit),
     })
   }
 
+  const postRunSafety = await verifyPostRunSafety(options, artifacts)
+
+  const layoutSummary = summarizeCoreLayout(messageOcr.layout)
   const summary = {
     ok: true,
     group: options.group,
     captureDir,
+    ocrEvidence: summarizeOcrEvidence(messageOcr),
+    layout: layoutSummary,
     recentMessages,
     downloads: localization.downloads,
     sent,
+    postRunSafety,
     artifacts,
   }
+  summary.actionEvidence = buildActionEvidence({
+    options,
+    opened,
+    sent,
+    downloads: localization.downloads,
+    postRunSafety,
+    artifacts,
+    layout: layoutSummary,
+  })
   fs.writeFileSync(path.join(captureDir, 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`)
   return summary
 }
@@ -682,6 +1706,10 @@ async function main() {
     recentLimit: takeOption(argv, '--recent-limit') || '5',
     captureDir: takeOption(argv, '--capture-dir'),
     downloadAttachmentsDir: takeOption(argv, '--download-attachments-dir'),
+    downloadExpectedTokens: takeMany(argv, '--download-expected-token'),
+    downloadLimit: takeOption(argv, '--download-limit'),
+    allowRightClickDownload: takeFlag(argv, '--allow-right-click-download'),
+    allowSearchOpen: takeFlag(argv, '--allow-search-open'),
     ocrUrl: takeOption(argv, '--ocr-url'),
     token: takeOption(argv, '--token'),
     ocrFixture: takeOption(argv, '--ocr-fixture'),