shennian 0.2.75 → 0.2.77

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

@@ -0,0 +1,707 @@
+#!/usr/bin/env node
+// @arch docs/features/wechat-rpa-channel.md
+// @test tests/wechat-rpa-win-visual.test.mjs
+
+import { spawn } from 'node:child_process'
+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'
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const helperBridge = path.join(repoRoot, 'scripts/wechat-rpa-win.mjs')
+
+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 --file C:\\tmp\\demo.png --file C:\\tmp\\demo.mp4 --ocr-fixture C:\\tmp\\search-ocr.json
+
+Options:
+  --group <name>          Required target group/conversation name.
+  --reply-text <text>     Text to send after opening the group.
+  --file <path>           File/image/video to send. Repeatable.
+  --recent-limit <n>      Number of OCR message observations to include in summary. Default: 5.
+  --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.
+  --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-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.`)
+}
+
+function takeOption(argv, name) {
+  const index = argv.indexOf(name)
+  if (index < 0) return null
+  const value = argv[index + 1]
+  if (!value || value.startsWith('--')) throw new Error(`Missing value for ${name}`)
+  argv.splice(index, 2)
+  return value
+}
+
+function takeMany(argv, name) {
+  const values = []
+  for (;;) {
+    const value = takeOption(argv, name)
+    if (value === null) break
+    values.push(value)
+  }
+  return values
+}
+
+function takeFlag(argv, name) {
+  const index = argv.indexOf(name)
+  if (index < 0) return false
+  argv.splice(index, 1)
+  return true
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+export function normalizeConversationName(value) {
+  return String(value || '')
+    .replace(/[\s\u200b\u200c\u200d]+/g, '')
+    .replace(/[（(]\d+[)）]$/g, '')
+    .trim()
+    .toLowerCase()
+}
+
+function normalizeText(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim()
+}
+
+function centerOfBox(box) {
+  return {
+    x: Number(box.x || 0) + Number(box.width || 0) / 2,
+    y: Number(box.y || 0) + Number(box.height || 0) / 2,
+  }
+}
+
+function observationText(row) {
+  return normalizeText(row?.text)
+}
+
+function observationConfidence(row) {
+  const value = Number(row?.confidence)
+  return Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0.75
+}
+
+function isSection(row) {
+  const text = observationText(row)
+  return SECTION_LABELS.has(text) || /^(群聊|联系人|聊天记录|公众号|小程序|企业微信)$/.test(text)
+}
+
+export function findConversationInSearchResults(observations, targetName) {
+  const target = normalizeConversationName(targetName)
+  if (!target) throw new Error('targetName is required')
+  const rows = (Array.isArray(observations) ? observations : [])
+    .filter(row => row?.box && observationText(row))
+    .map((row, index) => ({ row, index, text: observationText(row), center: centerOfBox(row.box) }))
+    .sort((a, b) => a.center.y - b.center.y || a.center.x - b.center.x)
+
+  const sections = rows.filter(item => isSection(item.row))
+  const groupSection = sections.find(item => item.text === '群聊')
+  const nextSection = groupSection
+    ? sections.find(item => item.center.y > groupSection.center.y + 0.002)
+    : null
+
+  const exactCandidates = rows.filter(item => normalizeConversationName(item.text) === target)
+  const sectionCandidates = groupSection
+    ? exactCandidates.filter(item => {
+        if (item.center.y <= groupSection.center.y) return false
+        if (nextSection && item.center.y >= nextSection.center.y) return false
+        return true
+      })
+    : []
+
+  const candidates = sectionCandidates.length > 0 ? sectionCandidates : exactCandidates
+  if (candidates.length === 0) return null
+
+  return candidates
+    .map(item => {
+      const sectionDistance = groupSection ? Math.max(0, item.center.y - groupSection.center.y) : item.center.y
+      const horizontalPenalty = item.center.x <= 1
+        ? Math.abs(item.center.x - 0.2) * 0.5
+        : Math.abs(item.center.x - 200) * 0.005
+      const score =
+        observationConfidence(item.row) * 100
+        + (groupSection && item.center.y > groupSection.center.y ? 50 : 0)
+        - sectionDistance * 5
+        - horizontalPenalty
+      return { ...item, score }
+    })
+    .sort((a, b) => b.score - a.score)[0].row
+}
+
+export function findTitleConfirmation(observations, targetName) {
+  const target = normalizeConversationName(targetName)
+  const rows = Array.isArray(observations) ? observations : []
+  return rows.find(row => normalizeConversationName(observationText(row)) === target) || null
+}
+
+export function isRetryableOcrError(status, body) {
+  if ([408, 429, 500, 502, 503, 504].includes(Number(status))) return true
+  return /invalid model response|timeout|temporar/i.test(String(body || ''))
+}
+
+export function pointFromObservation(capturePayload, observation, imageSize) {
+  if (!capturePayload?.bounds) throw new Error('capture payload missing bounds')
+  if (!observation?.box) throw new Error('observation missing box')
+  const bounds = capturePayload.bounds
+  const width = Number(imageSize?.width || bounds.width)
+  const height = Number(imageSize?.height || bounds.height)
+  const scaleX = Number(bounds.width) / width
+  const scaleY = Number(bounds.height) / height
+  const rawX = Number(observation.box.x)
+  const rawY = Number(observation.box.y)
+  const rawWidth = Number(observation.box.width)
+  const rawHeight = Number(observation.box.height)
+  const normalizedBox = Math.max(Math.abs(rawX), Math.abs(rawY), Math.abs(rawWidth), Math.abs(rawHeight)) <= 1
+  const cx = normalizedBox ? (rawX + rawWidth / 2) * width : rawX + rawWidth / 2
+  const cy = normalizedBox ? (rawY + rawHeight / 2) * height : rawY + rawHeight / 2
+  return {
+    x: Math.round(Number(bounds.x) + cx * scaleX),
+    y: Math.round(Number(bounds.y) + cy * scaleY),
+  }
+}
+
+export function geometryPoint(capturePayload, kind) {
+  const bounds = capturePayload?.mainWindow?.bounds || capturePayload?.bounds
+  if (!bounds) throw new Error('capture payload missing main window bounds')
+  const presets = {
+    search: [0.186, 0.087],
+    // Right-side composer: avoid the left search overlay and click inside the text area.
+    input: [0.58, 0.92],
+    send: [0.932, 0.945],
+  }
+  const pair = presets[kind]
+  if (!pair) throw new Error(`Unknown geometry point: ${kind}`)
+  return {
+    x: Math.round(Number(bounds.x) + Number(bounds.width) * pair[0]),
+    y: Math.round(Number(bounds.y) + Number(bounds.height) * pair[1]),
+  }
+}
+
+export function assertUsableMainWindow(capturePayload, phase = 'capture') {
+  const bounds = capturePayload?.mainWindow?.bounds || capturePayload?.bounds
+  if (!bounds) throw new Error(`${phase}: capture payload missing main window bounds`)
+  const width = Number(bounds.width)
+  const height = Number(bounds.height)
+  if (width < 760 || height < 600) {
+    throw new Error(
+      `${phase}: WeChat chat main window is not available; got ${Math.round(width)}x${Math.round(height)}. ` +
+        'The visible WeChat window looks like a login/prompt dialog, so the RPA flow was stopped.',
+    )
+  }
+  return capturePayload
+}
+
+export function readPngSize(filePath) {
+  const fd = fs.openSync(filePath, 'r')
+  try {
+    const buffer = Buffer.alloc(24)
+    fs.readSync(fd, buffer, 0, buffer.length, 0)
+    if (buffer.toString('ascii', 1, 4) !== 'PNG') throw new Error(`Not a PNG file: ${filePath}`)
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) }
+  } finally {
+    fs.closeSync(fd)
+  }
+}
+
+async function runBridge(args, options) {
+  const finalArgs = [helperBridge, ...args]
+  if (options.helper) finalArgs.push('--helper', options.helper)
+  const child = spawn(process.execPath, finalArgs, {
+    cwd: repoRoot,
+    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 (stderr.trim()) process.stderr.write(stderr)
+  if (exitCode !== 0) {
+    throw new Error(`wechat-rpa-win command failed (${exitCode}): ${args.join(' ')}\n${stdout}`)
+  }
+  const trimmed = stdout.trim()
+  if (!trimmed) return null
+  try {
+    return JSON.parse(trimmed)
+  } catch (error) {
+    throw new Error(`Invalid helper JSON for ${args.join(' ')}: ${error.message}\n${stdout}`)
+  }
+}
+
+async function capture(region, options, label) {
+  const file = path.join(options.captureDir, `${String(options.step++).padStart(2, '0')}-${label || region}.png`)
+  const result = await runBridge(['capture', '--region', region, '--output', file], options)
+  if (region === 'window') assertUsableMainWindow(result?.payload, label || region)
+  return { result, payload: result?.payload, file, imageSize: readPngSize(file) }
+}
+
+async function click(point, options, extra = []) {
+  return runBridge(['click', '--x', String(point.x), '--y', String(point.y), ...extra], options)
+}
+
+async function pasteText(text, options) {
+  return runBridge(['paste-text', '--text', text], options)
+}
+
+async function pasteFiles(files, options) {
+  return runBridge(['paste-files', ...files.flatMap(file => ['--file', file])], options)
+}
+
+async function press(keys, options) {
+  return runBridge(['press', '--keys', keys], options)
+}
+
+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}'.`)
+    }
+    return fixture
+  }
+  if (!options.ocrUrl) {
+    throw new Error('OCR is required for visual flow. Pass --ocr-url/--token or --ocr-fixture.')
+  }
+  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)
+    }
+    await sleep(400 * attempt)
+  }
+  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) {
+  return (Array.isArray(observations) ? observations : [])
+    .filter(row => observationText(row))
+    .slice(-limit)
+    .map(row => ({
+      text: observationText(row),
+      role: row.role || 'unknown',
+      confidence: observationConfidence(row),
+      ...(row.attachment ? { attachment: row.attachment } : {}),
+      box: row.box,
+    }))
+}
+
+function normalizedMessageText(value) {
+  return String(value || '').replace(/\s+/g, '').toLowerCase()
+}
+
+export function observationsContainText(observations, text) {
+  const target = normalizedMessageText(text)
+  if (!target) return true
+  return (Array.isArray(observations) ? observations : []).some(row => {
+    const content = normalizedMessageText(observationText(row))
+    return content.includes(target) || target.includes(content)
+  })
+}
+
+function basenameForAnyPlatform(file) {
+  const value = String(file || '')
+  return value.includes('\\') ? path.win32.basename(value) : path.basename(value)
+}
+
+function safeFileName(name) {
+  return path.basename(name || 'attachment')
+    .normalize('NFKC')
+    .replace(/[<>:"/\\|?*\x00-\x1F]/g, '_')
+    .replace(/\s+/g, ' ')
+    .replace(/^[ ._]+|[ ._]+$/g, '')
+    || 'attachment'
+}
+
+function uniqueInboundPath(dir, name, hash) {
+  const safe = safeFileName(name || 'attachment')
+  const ext = path.extname(safe)
+  const stem = ext ? safe.slice(0, -ext.length) : safe
+  const candidate = path.join(dir, safe)
+  if (!fs.existsSync(candidate)) return candidate
+  return path.join(dir, `${stem}-${hash.slice(0, 12)}${ext}`)
+}
+
+function mimeTypeFromExt(ext) {
+  const value = String(ext || '').toLowerCase()
+  if (['.jpg', '.jpeg'].includes(value)) return 'image/jpeg'
+  if (value === '.png') return 'image/png'
+  if (value === '.gif') return 'image/gif'
+  if (value === '.webp') return 'image/webp'
+  if (value === '.mp4') return 'video/mp4'
+  if (value === '.mov') return 'video/quicktime'
+  if (value === '.pdf') return 'application/pdf'
+  if (value === '.txt') return 'text/plain'
+  if (value === '.docx') return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+  if (value === '.xlsx') return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+  if (value === '.pptx') return 'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+  if (value === '.zip') return 'application/zip'
+  return 'application/octet-stream'
+}
+
+function attachmentTypeFromExt(ext) {
+  if (IMAGE_EXTENSIONS.has(String(ext || '').toLowerCase())) return 'image'
+  if (VIDEO_EXTENSIONS.has(String(ext || '').toLowerCase())) return 'video'
+  return 'file'
+}
+
+function postPasteDelayMs(file) {
+  const type = classifyOutboundFile(file).type
+  if (type === 'image') return 8_000
+  if (type === 'video') return 15_000
+  return 2_000
+}
+
+const IMAGE_EXTENSIONS = new Set(['.apng', '.avif', '.bmp', '.gif', '.heic', '.heif', '.jpeg', '.jpg', '.png', '.tif', '.tiff', '.webp'])
+const VIDEO_EXTENSIONS = new Set(['.3g2', '.3gp', '.avi', '.m4v', '.mkv', '.mov', '.mp4', '.mpeg', '.mpg', '.webm', '.wmv'])
+
+export function classifyOutboundFile(file) {
+  const name = basenameForAnyPlatform(file)
+  const ext = path.extname(name).toLowerCase()
+  const type = IMAGE_EXTENSIONS.has(ext) ? 'image' : VIDEO_EXTENSIONS.has(ext) ? 'video' : 'file'
+  return {
+    type,
+    name,
+    localPath: file,
+    availability: 'edge-local',
+  }
+}
+
+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))
+}
+
+function walkFiles(root, maxDepth, limit) {
+  const result = []
+  const stack = [{ dir: root, depth: 0 }]
+  while (stack.length && result.length < limit) {
+    const current = stack.pop()
+    let entries = []
+    try {
+      entries = fs.readdirSync(current.dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      const filePath = path.join(current.dir, entry.name)
+      if (entry.isDirectory()) {
+        if (current.depth < maxDepth) stack.push({ dir: filePath, depth: current.depth + 1 })
+        continue
+      }
+      if (!entry.isFile()) continue
+      try {
+        const stat = fs.statSync(filePath)
+        result.push({ path: filePath, size: stat.size, mtimeMs: stat.mtimeMs })
+      } catch {
+        // Ignore transient files while WeChat is writing them.
+      }
+    }
+  }
+  return result
+}
+
+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 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',
+  }
+}
+
+async function localizeInboundAttachments(recentMessages, messageCapture, options) {
+  if (options.downloadAttachments === false || !options.downloadAttachmentsDir) {
+    return { recentMessages, downloads: [] }
+  }
+  const targetDir = path.resolve(options.downloadAttachmentsDir)
+  fs.mkdirSync(targetDir, { recursive: true })
+  let before = snapshotDownloadCandidates()
+  const downloads = []
+  const updated = []
+  for (const message of recentMessages) {
+    const attachment = message.attachment
+    if (!attachment || attachment.localPath || attachment.url || !message.box) {
+      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 pending = {
+        ...message,
+        attachment: {
+          ...attachment,
+          availability: 'pending-download',
+          providerError: 'No new downloaded file was observed after clicking attachment bubble',
+        },
+      }
+      updated.push(pending)
+      downloads.push({ text: message.text, ok: false, providerError: pending.attachment.providerError })
+      before = snapshotDownloadCandidates()
+      continue
+    }
+    const localized = copyInboundAttachment(downloaded, 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()
+  }
+  return { recentMessages: updated, downloads }
+}
+
+export function missingConfirmedFiles(observations, files) {
+  const rows = Array.isArray(observations) ? observations : []
+  return (files || []).filter(file => {
+    const basename = basenameForAnyPlatform(file)
+    const normalizedBasename = normalizedMessageText(basename)
+    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)
+    })
+  })
+}
+
+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)) {
+      return initial
+    }
+  } catch (error) {
+    process.stderr.write(`Initial title OCR was skipped: ${error instanceof Error ? error.message : String(error)}\n`)
+  }
+
+  await click(geometryPoint(initial.payload, 'search'), options)
+  await sleep(180)
+  await press('^a', options)
+  await pasteText(options.group, options)
+  await sleep(650)
+
+  const searchCapture = await capture('window', options, 'search-results')
+  artifacts.push(searchCapture.file)
+  const searchOcr = await recognizeScreenshot(searchCapture, options, 'search-results')
+  const target = findConversationInSearchResults(searchOcr.observations, options.group)
+  if (!target) {
+    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)
+  await click(targetPoint, options, ['--no-raise'])
+  await sleep(350)
+  // WeChat 4.x can keep the transient search result panel open after clicking a result.
+  // Close it explicitly so later input/send geometry always targets the conversation composer.
+  await press('{ESC}', options)
+  await sleep(500)
+
+  const opened = await capture('window', options, 'opened-conversation')
+  artifacts.push(opened.file)
+  const titleOcr = await recognizeScreenshot(opened, options, 'title-confirmation')
+  if (!findTitleConfirmation(titleOcr.observations, options.group)) {
+    // 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}`)
+  }
+  return opened
+}
+
+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 })
+  const options = {
+    ...input,
+    captureDir,
+    step: 1,
+    recentLimit: Number(input.recentLimit || 5),
+    ocrTimeoutMs: Number(input.ocrTimeoutMs || 45_000),
+    openTimeoutMs: Number(input.openTimeoutMs || 12_000),
+  }
+  if (!options.group) throw new Error('--group is required')
+  const artifacts = []
+
+  const opened = await openConversationBySearch(options, artifacts)
+  const messageCapture = await capture('messages', options, 'messages-before-send')
+  artifacts.push(messageCapture.file)
+  const messageOcr = await recognizeScreenshot(messageCapture, options, 'message-read')
+  let recentMessages = summarizeObservations(messageOcr.observations, options.recentLimit)
+  const localization = await localizeInboundAttachments(recentMessages, messageCapture, options)
+  recentMessages = localization.recentMessages
+
+  const sent = []
+  if (!options.dryRun && options.replyText) {
+    await click(geometryPoint(opened.payload, 'input'), options)
+    await pasteText(options.replyText, options)
+    await sleep(250)
+    await press('{ENTER}', options)
+    await sleep(900)
+    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}`)
+    }
+    sent.push({ type: 'text', text: options.replyText, observations: summarizeObservations(confirmOcr.observations, options.recentLimit) })
+  }
+
+  if (!options.dryRun && options.files?.length) {
+    const confirmedFiles = []
+    const sentAttachments = []
+    const confirmationObservations = []
+    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)
+      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}`)
+      }
+      confirmedFiles.push(file)
+      sentAttachments.push(classifyOutboundFile(file))
+      confirmationObservations.push(...summarizeObservations(fileConfirmOcr.observations, options.recentLimit))
+    }
+    sent.push({
+      type: 'files',
+      files: confirmedFiles,
+      attachments: sentAttachments,
+      observations: confirmationObservations.slice(-options.recentLimit),
+    })
+  }
+
+  const summary = {
+    ok: true,
+    group: options.group,
+    captureDir,
+    recentMessages,
+    downloads: localization.downloads,
+    sent,
+    artifacts,
+  }
+  fs.writeFileSync(path.join(captureDir, 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`)
+  return summary
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    printHelp()
+    return
+  }
+  const files = takeMany(argv, '--file')
+  const options = {
+    group: takeOption(argv, '--group'),
+    replyText: takeOption(argv, '--reply-text'),
+    recentLimit: takeOption(argv, '--recent-limit') || '5',
+    captureDir: takeOption(argv, '--capture-dir'),
+    downloadAttachmentsDir: takeOption(argv, '--download-attachments-dir'),
+    ocrUrl: takeOption(argv, '--ocr-url'),
+    token: takeOption(argv, '--token'),
+    ocrFixture: takeOption(argv, '--ocr-fixture'),
+    helper: takeOption(argv, '--helper'),
+    channelId: takeOption(argv, '--channel-id'),
+    ocrTimeoutMs: Number(takeOption(argv, '--ocr-timeout-ms') || 45_000),
+    openTimeoutMs: Number(takeOption(argv, '--open-timeout-ms') || 12_000),
+    allowWeakTitle: takeFlag(argv, '--allow-weak-title'),
+    downloadAttachments: !takeFlag(argv, '--no-download-attachments'),
+    dryRun: takeFlag(argv, '--dry-run'),
+    files,
+  }
+  if (argv.length) throw new Error(`Unknown arguments: ${argv.join(' ')}`)
+  const summary = await runVisualFlow(options)
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`)
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(error => {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exit(1)
+  })
+}