2561 lines
105 KiB
Markdown
2561 lines
105 KiB
Markdown
# 微信 UI 自动化通用架构优化方案
|
||
|
||
> 文档版本：v3.0（速度优化版）
|
||
> 目标：将当前紧耦合于微信 4.x Linux 单一版本的 `xdotool_driver.py` 重构为可扩展、可校验、可恢复、高可用、高性能的通用微信 UI 自动化架构。
|
||
> 设计原则：
|
||
> - **最小可行实现优先**：每一阶段都可独立交付并产生可见收益，不允许大爆炸式重构
|
||
> - **高可用优先**：每一处都考虑并发/竞态/超时/泄漏/降级/熔断/恢复
|
||
> - **速度优先**：固定 sleep 改自适应等待、会话缓存、DB 校验调优、并行化
|
||
> - **失败可观测**：所有失败都可被监控、分类、定位
|
||
|
||
---
|
||
|
||
## 一、背景与现状
|
||
|
||
### 1.1 当前实现
|
||
|
||
当前微信 UI 自动化全部集中在 [bridge/woc_bridge/ui/xdotool_driver.py](../bridge/woc_bridge/ui/xdotool_driver.py)（约 2000+ 行单文件），实现方式：
|
||
|
||
- 通过 `xdotool search --name "微信"` 找窗口（[xdotool_driver.py:128](../bridge/woc_bridge/ui/xdotool_driver.py#L128)）
|
||
- 通过 `getwindowgeometry` 拿窗口 (X, Y, W, H)
|
||
- 通过**硬编码像素偏移**计算关键 UI 元素位置（[xdotool_driver.py:391-396](../bridge/woc_bridge/ui/xdotool_driver.py#L391)）
|
||
- 通过 `xdotool click` 点击，`xdotool type` 输入文本
|
||
- 每步之间 `sleep 1.0s` 等待 UI 响应
|
||
- send_queue 串行化（[messaging/send_queue.py](../bridge/woc_bridge/messaging/send_queue.py)），相邻消息最小 3000ms 间隔
|
||
|
||
### 1.2 已确认的核心问题（含高可用性复核新增）
|
||
|
||
#### 1.2.1 功能正确性问题
|
||
|
||
| 问题 | 根因 | 后果 |
|
||
|---|---|---|
|
||
| 分辨率/DPI 一变即崩 | 像素偏移硬编码（[xdotool_driver.py:391-396](../bridge/woc_bridge/ui/xdotool_driver.py#L391)） | 1280x720 下点击位置错位 |
|
||
| 微信更新布局即崩 | 坐标常量 + 菜单顺序写死 | 撤回可能变成删除，造成数据丢失 |
|
||
| 无法校验操作结果 | 只返回本地生成的 `local_<ts>_<rand>` ID | 已记录过"返回 200 但消息未发出" |
|
||
| 重试即重发 | 无幂等键 | 网络抖动造成重复消息 |
|
||
| 失败后状态不可知 | 线性脚本，无状态机 | 搜索框开着、焦点错位、下一次必败 |
|
||
| experimental 功能残留失效代码 | forward/add_friend/set_remark 仍用 `ctrl+f`/`ctrl+a` | 实际跑不通 |
|
||
|
||
#### 1.2.2 高可用性问题（v2.0 新增复核）
|
||
|
||
| 问题 | 严重程度 | 根因 |
|
||
|---|---|---|
|
||
| `asyncio.wait_for` 取消导致 xdotool 子进程泄漏 | **严重** | `_step` 的 deadline 先于 `_run` 内 15s 超时触发，取消时 `communicate` 被停但子进程未 kill |
|
||
| 调试截图打满磁盘 | **严重** | `_DEBUG_SCREENSHOTS=True` 每次发送写 5 张 PNG ≈ 5-10MB，一周打满容器磁盘 |
|
||
| L1/L2 超时层级冲突 | **严重** | `max(1.0, remaining)` 在剩余 < 15s 时会先于 `_CMD_TIMEOUT_SEC=15s` 触发，导致子进程泄漏 |
|
||
| DB 校验失败 ≠ 发送失败 | **严重** | [routes/send.py:265](../bridge/woc_bridge/routes/send.py#L265) 把 `verified=false` 直接抛 `SEND_FAILED`，导致调用方重试即重发 |
|
||
| 幂等键缺 `client_request_id` 维度 | **严重** | 用户主动重发相同内容会被误吞 |
|
||
| DB 校验未验证 `talker == to_wxid` | **严重** | display_name 串号时幂等会"成功"掩盖发错人 |
|
||
| bridge 启动时不做全量清场 | **致命** | 上次崩溃残留脏状态（搜索框打开/输入框有内容），下一次必败 |
|
||
| `_reset_to_idle` 无 post_verify | **严重** | Esc + BackSpace 无法覆盖 webview/多级菜单/输入法候选框等状态 |
|
||
| 无错误分类 | **严重** | 所有失败都抛 `SEND_FAILED`，调用方无法区分可重试 vs 不可重试 |
|
||
| 无崩溃 watchdog | **严重** | 微信/Xvnc 崩溃后 bridge 不主动感知，需人工触发 autofix |
|
||
| 无 Prometheus metric | **严重** | 纯文本日志无法做趋势分析，无法感知模板失效/失败率突增 |
|
||
| 无熔断机制 | **严重** | DB 校验/图像匹配连续失败仍每次重试，浪费时间且可能造成重复发送 |
|
||
|
||
#### 1.2.3 速度问题（v3.0 新增复核）
|
||
|
||
通过逐行代码分析 [xdotool_driver.py:455-545](../bridge/woc_bridge/ui/xdotool_driver.py#L455)（`_open_session_by_name`）与 [xdotool_driver.py:550-611](../bridge/woc_bridge/ui/xdotool_driver.py#L550)（`send_text`），实测时序拆解如下：
|
||
|
||
| 阶段 | 步骤 | 耗时 | 类型 |
|
||
|---|---|---|---|
|
||
| 会话定位 | find_wechat_window | ~50ms | xdotool |
|
||
| | _activate_window_fast | ~2s | windowactivate + 轮询 |
|
||
| | sleep 1.0s × 7 处 | **7.0s** | **固定 sleep** |
|
||
| | _click_at × 2 | ~200ms | xdotool |
|
||
| | _key × 4 | ~200ms | xdotool |
|
||
| | _paste_via_xclip (name) | ~200ms | xdotool type |
|
||
| | _debug_screenshot × 1 | ~100ms | scrot + 文件 |
|
||
| 会话定位小计 | | **~10s** | |
|
||
| 发送体 | _debug_screenshot × 4 | ~400ms | scrot + 文件 |
|
||
| | _click_input_box | ~100ms | xdotool |
|
||
| | _paste_via_xclip (content) | ~200ms | xdotool type |
|
||
| | sleep 1.0s × 2 处 | **2.0s** | **固定 sleep** |
|
||
| | _click_send_button | ~100ms | xdotool |
|
||
| 发送体小计 | | **~3s** | |
|
||
| DB 校验 | _verify_sent_to_talker | **0-10s** | 轮询 0.5s 间隔 |
|
||
| 队列延时 | send_delay_ms | **3.0s** | 任务后强制 sleep |
|
||
| **总计（典型）** | | **~16s** | |
|
||
| **总计（最坏）** | | **~26s** | DB 校验 10s + 全部 sleep |
|
||
|
||
**核心发现**：
|
||
1. **固定 sleep 是最大成本**：10 处 `sleep 1.0s` = 10s，占会话定位总耗时的 70%
|
||
2. **DB 校验超时过长**：10s 超时 + 0.5s 轮询间隔，实际微信 DB 写入通常 < 500ms
|
||
3. **调试截图在关键路径上**：5 张截图 × ~100ms = 500ms，且写磁盘有 I/O 开销
|
||
4. **无会话缓存**：每次都重新搜索会话，即使连续发给同一人
|
||
5. **_click_at 分两条命令**：mousemove + click 分两次 fork，可合并
|
||
6. **DB 查询与 UI 操作串行**：发送前查 latest_msg_id 与激活窗口串行，可并行
|
||
|
||
**结论**：xdotool 命令本身执行很快（毫秒级），**慢在固定 sleep 与串行化等待**。优化空间巨大，预期可从 16s 降到 3-5s（首条）/ 1-2s（同联系人后续）。
|
||
|
||
### 1.3 微信 4.x Linux 技术约束（决定方案边界）
|
||
|
||
通过项目代码与文档调研确认：
|
||
|
||
1. **主聊天 UI = Qt 自绘**（[docker/Dockerfile:28](../docker/Dockerfile#L28) 注释"微信原生版是 Qt 程序"）
|
||
2. **WeChatAppEx = Chromium 内核**（[docker/Dockerfile:41](../docker/Dockerfile#L41) 注释），承载小程序/公众号文章/朋友圈 webview
|
||
3. **RadiumWMPF 不响应 X11 修饰键组合**（如 Ctrl+V），只响应单字符事件（项目记忆已确认）
|
||
4. **不暴露 AT-SPI accessibility 树**：Qt 自绘 + Chromium 默认懒启用，dogtail/pyatspi 全部失效
|
||
5. **主进程不吃命令行参数**（[docker/autostart:23-25](../docker/autostart#L23) 注释），无法直接通过 `--remote-debugging-port` 开启 CDP
|
||
6. **send_queue 已实现串行化但无锁、无幂等、无重试**（[send_queue.py:117](../bridge/woc_bridge/messaging/send_queue.py#L117)）
|
||
7. **DB 校验已实现但错误处理不当**（[routes/send.py:107](../bridge/woc_bridge/routes/send.py#L107) `_verify_sent_to_talker`，10s 轮询）
|
||
|
||
**核心结论**：单一方案无法覆盖所有场景。必须采用**混合方案**——Qt 自绘 UI 用「图像识别 + xdotool」，CEF 部分用 CDP（若可开启），所有操作用状态机编排 + DB 校验兜底，**并补齐所有高可用性机制**。
|
||
|
||
---
|
||
|
||
## 二、技术路径选型
|
||
|
||
### 2.1 候选方案对比
|
||
|
||
| 方案 | 覆盖范围 | 元素识别 | 跨版本 | 实施成本 | 风险 | 决策 |
|
||
|---|---|---|---|---|---|---|
|
||
| A. xdotool + 像素坐标（当前） | 全部 | 无 | 差 | 已实现 | 中 | 作为兜底保留 |
|
||
| B. AT-SPI / dogtail | 失效 | - | - | - | - | **不可用**，Qt 自绘无 a11y 树 |
|
||
| C. 纯图像识别（OpenCV） | 全部 | 有（模板匹配） | 中（需多模板） | 中 | 低 | **采用** |
|
||
| D. CDP 协议 | 仅 CEF 部分 | 完整 DOM | 强 | 中高 | 中 | **PoC 后决定** |
|
||
| E. Frida native hook | 全部 | 函数级 | 强 | 极高 | 高（封号） | **不采用** |
|
||
| F. pyautogui | 与 xdotool 同 | 同 X11 XTest | 同 | 低 | 同 | **不采用**，无实质改进 |
|
||
|
||
### 2.2 选型理由
|
||
|
||
- **pyautogui 与 xdotool 底层完全相同**（都用 X11 XTest 扩展），换皮不解决"微信不响应修饰键"的根本问题
|
||
- **AT-SPI 路线对 Qt 自绘应用完全失效**：自绘控件不实现 `QAccessibleInterface`，a11y 树里只有空 pane，dogtail 拿不到任何可交互节点
|
||
- **CDP 路线可行性未验证**：主进程不吃命令行参数，需 LD_PRELOAD 注入或独立启动 WeChatAppEx，ROI 存疑
|
||
- **OpenCV 图像识别 + xdotool 执行**是当前最务实路径：保留现有执行链路，仅在定位层加图像校验，最小改动
|
||
|
||
### 2.3 最终技术栈
|
||
|
||
```
|
||
定位层：OpenCV 模板匹配（cv2.matchTemplate 多尺度）+ 窗口几何兜底
|
||
执行层：xdotool（保留现有 X11 XTest 链路）
|
||
编排层：自写异步状态机（不引入 transitions 库）
|
||
校验层：DB 回读（ground truth）+ 截图对比（降级兜底）
|
||
去重层：基于 (to_wxid + content_hash + client_request_id) 的 5 分钟幂等窗口
|
||
扩展点：CDP 后端（PoC 验证后再实现）
|
||
高可用：熔断器 + watchdog + 错误分类 + Prometheus metric + 资源回收
|
||
```
|
||
|
||
---
|
||
|
||
## 三、目标架构（六层分层 + 高可用横切）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Layer 6: Capability API（对外稳定接口） │
|
||
│ send_text / send_image / publish_moment / revoke / forward │
|
||
└────────────────────────┬────────────────────────────────────────┘
|
||
│
|
||
┌────────────────────────┴────────────────────────────────────────┐
|
||
│ Layer 5: Flow Orchestrator（流程编排 + 幂等 + 重试 + 熔断） │
|
||
│ FlowOrchestrator + IdemCache + CircuitBreaker + SendQueue │
|
||
└────────────────────────┬────────────────────────────────────────┘
|
||
│
|
||
┌────────────────────────┴────────────────────────────────────────┐
|
||
│ Layer 4: Flow State Machine（流程状态机 + 回滚 + 启动清场） │
|
||
│ Flow 基类 / SendTextFlow / PublishMomentFlow / ... │
|
||
│ 每 transition: pre_guard → action → post_verify → on_failure │
|
||
└────────────────────────┬────────────────────────────────────────┘
|
||
│
|
||
┌────────────────────────┴────────────────────────────────────────┐
|
||
│ Layer 3: Action Library（原子动作，可组合） │
|
||
│ click_element / type_text / key_press / wait_for / screenshot │
|
||
└────────────────────────┬────────────────────────────────────────┘
|
||
│
|
||
┌────────────────────────┴────────────────────────────────────────┐
|
||
│ Layer 2: Locator Strategies（多策略定位，可插拔） │
|
||
│ ImageLocator（OpenCV）/ GeomLocator（像素兜底）/ CDPLocator │
|
||
│ 统一 Selector → ElementHandle 接口 │
|
||
└────────────────────────┬────────────────────────────────────────┘
|
||
│
|
||
┌────────────────────────┴────────────────────────────────────────┐
|
||
│ Layer 1: Backend Adapters（执行后端，多驱动并存） │
|
||
│ XdotoolBackend / OpenCVBackend / CDPBackend（可选） │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
|
||
横切关注点（贯穿所有层）：
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ HA: Watchdog（微信/Xvnc 崩溃感知） │
|
||
│ HA: Metrics（Prometheus 端点） │
|
||
│ HA: ResourceReaper（截图清理 / 模板 LRU / 子进程收尸） │
|
||
│ HA: ErrorClassifier（错误码分类 + 重试策略） │
|
||
│ HA: TraceID（贯穿单次请求的所有日志行） │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.1 分层职责
|
||
|
||
| 层 | 职责 | 不做什么 |
|
||
|---|---|---|
|
||
| L1 Backend | 执行原子操作（click/type/screenshot） | 不做元素定位，不做流程编排 |
|
||
| L2 Locator | 找元素位置，返回 ElementHandle | 不执行点击，不决定流程顺序 |
|
||
| L3 Action | 组合 L1+L2 完成有语义的原子动作（如"点击并校验"） | 不跨步骤 |
|
||
| L4 Flow | 编排多步骤完成业务流程（如"发文本"） | 不直接调 xdotool |
|
||
| L5 Orchestrator | 幂等检查、入队、重试策略、熔断 | 不关心 UI 细节 |
|
||
| L6 Capability | 对外稳定的业务 API | 不关心实现后端 |
|
||
|
||
### 3.2 依赖方向
|
||
|
||
```
|
||
L6 → L5 → L4 → L3 → L2 → L1
|
||
L4 可直接调 L3，不绕道 L2（Action 内部组合 L1+L2）
|
||
L5 可直接访问 DB（用于幂等与校验），不绕道 L4
|
||
横切 HA 模块可被任意层调用
|
||
```
|
||
|
||
### 3.3 并发模型（关键决策）
|
||
|
||
**决策：串行化只在 `send_queue` 一层，Flow 内部不再加锁**
|
||
|
||
**理由**：send_queue 的单 worker + asyncio.Queue 已经保证了"同一时刻只有一个 Flow 在跑"（[send_queue.py:117](../bridge/woc_bridge/messaging/send_queue.py#L117) 的 `while True` 循环）。如果在 Flow 内再加 `asyncio.Lock` 会形成"双重串行"，不死锁但语义混乱、排障困难。
|
||
|
||
**只读探测的并发处理**：
|
||
- `detect_login_state` / `is_wechat_running` / `get_window_geometry` 等只读探测走队列外快速路径
|
||
- 但需共享一把**轻量 `asyncio.Lock`** 与发送操作互斥，避免探测期间被发送操作打断
|
||
- 探测用 `with lock`，发送也用 `with lock`，但发送额外受队列节流
|
||
|
||
```python
|
||
# bridge/ui/backends/xdotool.py
|
||
class XdotoolBackend:
|
||
def __init__(self, display: str = ":1"):
|
||
self.display = display
|
||
self._ui_lock = asyncio.Lock() # UI 单焦点保护
|
||
|
||
async def click(self, x: int, y: int) -> None:
|
||
async with self._ui_lock:
|
||
# 实际点击
|
||
...
|
||
```
|
||
|
||
**注意**：这把锁的粒度是"单次原子操作"，不是"整个 Flow"。Flow 的串行性由 send_queue 保证，锁只防止探测与发送的并发冲突。
|
||
|
||
### 3.4 多实例隔离（MVP 不涉及，但架构必须预留）
|
||
|
||
**问题**：当前 `config.py:126` `display: str = ":1"` 是全局单例。两个微信实例共享同一 X server 时，`xdotool search --name "微信"` 跨实例匹配，鼠标键盘事件跨实例串扰。
|
||
|
||
**架构预留**：
|
||
- `XdotoolBackend` 必须接受 `display` 参数（当前已做到，[xdotool_driver.py:39](../bridge/woc_bridge/ui/xdotool_driver.py#L39)）
|
||
- `xdotool search` 改用 `--pid <wechat_pid>` 精确匹配本实例进程的窗口
|
||
- `AppState` 改为 per-instance 而非全局单例（属于阶段 5 多应用框架）
|
||
- **MVP 阶段单实例，不触发此问题**
|
||
|
||
---
|
||
|
||
## 四、核心模块详细设计
|
||
|
||
### 4.1 Layer 1 - Backend Adapters
|
||
|
||
**职责**：把现有的 `xdotool` 调用、`scrot` 截图、`getwindowgeometry` 等封装为统一后端接口。**不做元素定位**。
|
||
|
||
#### 4.1.1 BackendProtocol 定义
|
||
|
||
```python
|
||
# bridge/ui/backends/base.py
|
||
from abc import ABC, abstractmethod
|
||
from dataclasses import dataclass
|
||
import asyncio
|
||
|
||
@dataclass
|
||
class WindowGeometry:
|
||
x: int; y: int; width: int; height: int
|
||
|
||
class BackendProtocol(ABC):
|
||
"""所有执行后端必须实现的原子能力。"""
|
||
|
||
@abstractmethod
|
||
async def click(self, x: int, y: int) -> None:
|
||
"""在屏幕绝对坐标点击。"""
|
||
|
||
@abstractmethod
|
||
async def type_text(self, text: str) -> None:
|
||
"""逐字符输入文本（xdotool type，绕过修饰键问题）。"""
|
||
|
||
@abstractmethod
|
||
async def key_press(self, key: str, repeat: int = 1) -> None:
|
||
"""按键，支持 repeat。"""
|
||
|
||
@abstractmethod
|
||
async def screenshot(self) -> bytes:
|
||
"""截全屏，返回 PNG bytes。"""
|
||
|
||
@abstractmethod
|
||
async def get_window_geometry(self, window_title: str) -> WindowGeometry:
|
||
"""按窗口标题找窗口并返回几何。"""
|
||
|
||
@abstractmethod
|
||
async def activate_window(self, window_title: str) -> None:
|
||
"""激活指定窗口。"""
|
||
|
||
@property
|
||
def capabilities(self) -> set[str]:
|
||
"""该后端支持的能力集合。"""
|
||
return {"click", "type", "key", "screenshot", "window"}
|
||
```
|
||
|
||
#### 4.1.2 XdotoolBackend 实现（含超时与取消安全）
|
||
|
||
**关键高可用性设计**：`_run` 改为上下文管理器，确保任何取消场景下子进程都被 kill + wait 收尸。
|
||
|
||
```python
|
||
# bridge/ui/backends/xdotool.py
|
||
import asyncio
|
||
import os
|
||
import logging
|
||
from contextlib import asynccontextmanager
|
||
from typing import Optional, AsyncIterator
|
||
|
||
logger = logging.getLogger("woc-bridge")
|
||
|
||
# 分层超时（关键决策，解决 L1/L2 冲突）
|
||
_CMD_TIMEOUT_SEC = 5.0 # L1: 单命令超时，防子进程挂死（从 15s 降到 5s）
|
||
_STEP_MIN_TIMEOUT_SEC = 7.0 # L2: 单步骤超时下限 = L1 + 2s，避免 L2 先于 L1 触发
|
||
_FLOW_TIMEOUT_SEC = 30.0 # L3: 整流程超时
|
||
_HTTP_TIMEOUT_SEC = 60.0 # L4: HTTP 请求超时 = L3 + DB 校验 10s + 余量
|
||
|
||
class XdotoolBackend(BackendProtocol):
|
||
def __init__(self, display: str = ":1"):
|
||
self.display = display
|
||
self._ui_lock = asyncio.Lock() # UI 单焦点保护（与只读探测共享）
|
||
|
||
def _env(self) -> dict:
|
||
env = dict(os.environ)
|
||
env["DISPLAY"] = self.display
|
||
return env
|
||
|
||
@asynccontextmanager
|
||
async def _run_managed(self, args: list[str]) -> AsyncIterator[tuple[int, bytes, bytes]]:
|
||
"""安全的子进程执行上下文管理器。
|
||
|
||
保证：
|
||
- 无论协程如何退出（正常返回/超时/取消/异常），子进程都会被 kill + wait
|
||
- 超时不重试，退避交给上层
|
||
"""
|
||
proc = await asyncio.create_subprocess_exec(
|
||
*args,
|
||
stdout=asyncio.subprocess.PIPE,
|
||
stderr=asyncio.subprocess.PIPE,
|
||
env=self._env(),
|
||
)
|
||
try:
|
||
try:
|
||
stdout, stderr = await asyncio.wait_for(
|
||
proc.communicate(),
|
||
timeout=_CMD_TIMEOUT_SEC,
|
||
)
|
||
yield proc.returncode, stdout, stderr
|
||
except (asyncio.TimeoutError, asyncio.CancelledError):
|
||
# 超时或取消时，显式 kill + wait 收尸，防孤儿进程
|
||
proc.kill()
|
||
try:
|
||
await asyncio.wait_for(proc.wait(), timeout=5.0)
|
||
except asyncio.TimeoutError:
|
||
logger.error("[backend] proc.wait() 超时，孤儿进程残留: %s", args[0])
|
||
raise
|
||
except Exception:
|
||
# 兜底：任何异常都确保 kill
|
||
if proc.returncode is None:
|
||
proc.kill()
|
||
try:
|
||
await proc.wait()
|
||
except Exception:
|
||
pass
|
||
raise
|
||
|
||
async def _run(self, args: list[str]) -> tuple[int, bytes, bytes]:
|
||
"""执行一条命令并返回 (returncode, stdout, stderr)。"""
|
||
async with self._run_managed(args) as result:
|
||
return result
|
||
|
||
async def click(self, x: int, y: int) -> None:
|
||
async with self._ui_lock:
|
||
await self._run(["xdotool", "mousemove", "--sync", str(x), str(y)])
|
||
await self._run(["xdotool", "click", "1"])
|
||
|
||
async def type_text(self, text: str) -> None:
|
||
async with self._ui_lock:
|
||
await self._run(["xdotool", "type", "--", text])
|
||
|
||
async def key_press(self, key: str, repeat: int = 1) -> None:
|
||
async with self._ui_lock:
|
||
args = ["xdotool", "key"]
|
||
if repeat > 1:
|
||
args.extend(["--repeat", str(repeat)])
|
||
args.append(key)
|
||
await self._run(args)
|
||
|
||
async def screenshot(self) -> bytes:
|
||
"""截图并返回 PNG bytes（不写文件，避免磁盘泄漏）。"""
|
||
async with self._ui_lock:
|
||
proc = await asyncio.create_subprocess_exec(
|
||
["scrot", "-o", "-"], # 输出到 stdout
|
||
stdout=asyncio.subprocess.PIPE,
|
||
stderr=asyncio.subprocess.DEVNULL,
|
||
env=self._env(),
|
||
)
|
||
try:
|
||
stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=5.0)
|
||
return stdout
|
||
except (asyncio.TimeoutError, asyncio.CancelledError):
|
||
proc.kill()
|
||
await proc.wait()
|
||
raise
|
||
```
|
||
|
||
**关键改进**：
|
||
1. `_CMD_TIMEOUT_SEC` 从 15s 降到 5s（xdotool 命令本身是毫秒级，5s 足够兜底）
|
||
2. `_run_managed` 上下文管理器确保任何取消场景都 kill + wait
|
||
3. 截图用 `scrot -o -` 输出到 stdout，**不写文件**，避免磁盘泄漏
|
||
4. `_ui_lock` 保护 UI 单焦点
|
||
|
||
#### 4.1.3 OpenCVBackend（图像识别专用）
|
||
|
||
```python
|
||
# bridge/ui/backends/opencv.py
|
||
import cv2
|
||
import numpy as np
|
||
from collections import OrderedDict
|
||
from typing import Optional
|
||
|
||
class OpenCVBackend:
|
||
"""图像识别后端，只做 find_element，不执行点击。"""
|
||
|
||
def __init__(self, template_dir: str, max_cache_size: int = 20):
|
||
self.template_dir = template_dir
|
||
# LRU 模板缓存，上限 20 个（避免内存泄漏）
|
||
self._cache: OrderedDict[str, np.ndarray] = OrderedDict()
|
||
self._max_cache_size = max_cache_size
|
||
|
||
def _load_template(self, name: str) -> np.ndarray:
|
||
if name in self._cache:
|
||
self._cache.move_to_end(name) # LRU 更新
|
||
return self._cache[name]
|
||
path = os.path.join(self.template_dir, name)
|
||
img = cv2.imread(path, cv2.IMREAD_GRAYSCALE)
|
||
if img is None:
|
||
raise FileNotFoundError(f"模板不存在: {path}")
|
||
self._cache[name] = img
|
||
if len(self._cache) > self._max_cache_size:
|
||
self._cache.popitem(last=False) # LRU 淘汰
|
||
return img
|
||
|
||
async def find_template(
|
||
self, screenshot_png: bytes, template_name: str,
|
||
threshold: float = 0.80,
|
||
scales: list[float] = None,
|
||
roi: Optional[tuple[int, int, int, int]] = None,
|
||
) -> Optional[tuple[int, int, int, int, float]]:
|
||
"""在截图中找模板，返回 (x, y, w, h, confidence) 或 None。
|
||
|
||
Args:
|
||
screenshot_png: PNG bytes
|
||
template_name: 模板文件相对路径
|
||
threshold: 匹配阈值（默认 0.80）
|
||
scales: 多尺度匹配列表（默认 [1.0, 0.75, 1.25, 1.5]）
|
||
roi: (x, y, w, h) 限制搜索区域（窗口几何内），None 表示全屏
|
||
"""
|
||
scales = scales or [1.0, 0.75, 1.25, 1.5]
|
||
# PNG bytes → np.ndarray（灰度）
|
||
img_arr = np.frombuffer(screenshot_png, np.uint8)
|
||
img = cv2.imdecode(img_arr, cv2.IMREAD_GRAYSCALE)
|
||
if roi:
|
||
x, y, w, h = roi
|
||
img = img[y:y+h, x:x+w]
|
||
tpl = self._load_template(template_name)
|
||
|
||
best_val, best_loc, best_size = 0.0, None, (0, 0)
|
||
# 逐个尺度处理，避免并行加载多个缩放图占内存
|
||
for scale in scales:
|
||
scaled = cv2.resize(tpl, None, fx=scale, fy=scale)
|
||
res = cv2.matchTemplate(img, scaled, cv2.TM_CCOEFF_NORMED)
|
||
_, max_val, _, max_loc = cv2.minMaxLoc(res)
|
||
if max_val > best_val:
|
||
best_val = max_val
|
||
best_loc = max_loc
|
||
best_size = (scaled.shape[1], scaled.shape[0])
|
||
del scaled, res # 显式释放
|
||
|
||
if best_val < threshold:
|
||
return None
|
||
# 如果用了 ROI，坐标要加上 ROI 偏移
|
||
if roi:
|
||
best_loc = (best_loc[0] + roi[0], best_loc[1] + roi[1])
|
||
return (best_loc[0], best_loc[1], best_size[0], best_size[1], best_val)
|
||
```
|
||
|
||
**关键改进**：
|
||
1. LRU 模板缓存上限 20 个（每个约 2MB，总上限 40MB）
|
||
2. 多尺度匹配**逐个处理**，显式 `del` 释放，避免并行占内存
|
||
3. 支持 ROI 限制（只在窗口区域内搜），性能提升约 4 倍
|
||
4. 返回置信度，供熔断决策
|
||
|
||
### 4.2 Layer 2 - Locator Strategies
|
||
|
||
**职责**：把"找元素"与"点元素"分离。
|
||
|
||
```python
|
||
# bridge/ui/locators/base.py
|
||
from dataclasses import dataclass, field
|
||
from typing import Optional
|
||
|
||
@dataclass
|
||
class GeomSpec:
|
||
"""窗口几何相对坐标兜底定位。"""
|
||
relative_to: str = "window" # window / window_top_left / window_bottom_right
|
||
x_ratio: float = 0.0
|
||
y_ratio: float = 0.0
|
||
x_offset: int = 0
|
||
y_offset: int = 0
|
||
|
||
@dataclass
|
||
class Selector:
|
||
"""声明式元素选择器，可同时配置多种定位策略。"""
|
||
kind: str # 'search_box' / 'send_button' / 'input_box'
|
||
by_image: Optional[str] = None # 模板图文件名
|
||
by_geom: Optional[GeomSpec] = None # 几何兜底
|
||
threshold: float = 0.80 # 图像匹配阈值
|
||
require_image: bool = False # 高风险操作设 True，图像失败即拒绝
|
||
description: str = ""
|
||
|
||
@dataclass
|
||
class ElementHandle:
|
||
"""统一的元素句柄，由 Locator 产出。"""
|
||
selector: Selector
|
||
x: int; y: int
|
||
w: int = 0; h: int = 0
|
||
confidence: float = 1.0
|
||
strategy: str = "geom" # 'image' / 'geom'
|
||
|
||
@property
|
||
def center(self) -> tuple[int, int]:
|
||
return (self.x, self.y)
|
||
```
|
||
|
||
**LocatorRegistry** 加载 YAML profile，按 `(app_version, resolution)` 选择：
|
||
|
||
```python
|
||
# bridge/ui/locators/registry.py
|
||
class LocatorRegistry:
|
||
"""加载 UI profile YAML，提供 selector 查询。
|
||
|
||
支持深色/浅色模式切换（通过运行时 set_theme）。
|
||
"""
|
||
|
||
def __init__(self, profile_dir: str, opencv: OpenCVBackend):
|
||
self.profile_dir = profile_dir
|
||
self.opencv = opencv
|
||
self.selectors: dict[str, Selector] = {}
|
||
self.theme: str = "light" # 'light' / 'dark'
|
||
self._fail_counts: dict[str, int] = {} # per-kind 失败计数（熔断用）
|
||
self._circuit_open_until: dict[str, float] = {} # per-kind 熔断截止时间
|
||
|
||
def load(self, app_version: str, resolution: tuple[int, int]) -> None:
|
||
"""按 (版本, 分辨率) 加载最匹配的 profile。"""
|
||
candidates = [
|
||
f"wechat_{app_version}_{resolution[0]}x{resolution[1]}.yaml",
|
||
f"wechat_{app_version}.yaml",
|
||
"default.yaml",
|
||
]
|
||
for fname in candidates:
|
||
path = os.path.join(self.profile_dir, fname)
|
||
if os.path.exists(path):
|
||
self._load_yaml(path)
|
||
logger.info("[locator] 加载 profile: %s", fname)
|
||
return
|
||
logger.warning("[locator] 无可用 UI profile，回退到硬编码默认值")
|
||
self._load_defaults()
|
||
|
||
def set_theme(self, theme: str) -> None:
|
||
"""切换深色/浅色模式模板目录。"""
|
||
if theme != self.theme:
|
||
self.theme = theme
|
||
logger.info("[locator] 切换主题: %s", theme)
|
||
|
||
def get(self, kind: str) -> Selector:
|
||
return self.selectors.get(kind) or self._default_selector(kind)
|
||
|
||
def is_circuited(self, kind: str) -> bool:
|
||
"""该 kind 的图像匹配是否被熔断。"""
|
||
deadline = self._circuit_open_until.get(kind, 0)
|
||
return time.monotonic() < deadline
|
||
|
||
def record_image_failure(self, kind: str) -> None:
|
||
"""记录图像匹配失败，连续 10 次触发熔断 5 分钟。"""
|
||
self._fail_counts[kind] = self._fail_counts.get(kind, 0) + 1
|
||
if self._fail_counts[kind] >= 10:
|
||
self._circuit_open_until[kind] = time.monotonic() + 300
|
||
logger.warning("[locator] kind=%s 图像匹配熔断 5 分钟", kind)
|
||
|
||
def record_image_success(self, kind: str) -> None:
|
||
"""记录图像匹配成功，重置失败计数。"""
|
||
self._fail_counts[kind] = 0
|
||
self._circuit_open_until.pop(kind, None)
|
||
```
|
||
|
||
**Profile YAML 示例**（`bridge/ui/profiles/wechat_4.0_1920x1080.yaml`）：
|
||
|
||
以下坐标基于用户实际截图估算：
|
||
- 容器分辨率 `1920x1080`，DPI 96，浅色模式
|
||
- 左侧会话栏宽度约 300px
|
||
- 搜索框位于左栏顶部，未激活状态为空白输入框
|
||
- 发送按钮位于右下角，激活态为绿色
|
||
|
||
```yaml
|
||
# 微信 4.0 Linux, 1920x1080 分辨率，浅色模式
|
||
# 截图参考：bridge/ui/profiles/templates/screenshot/03-主界面.png
|
||
search_box:
|
||
by_image: "wechat_4.0/light/search_box.png"
|
||
# 裁剪建议：从 03-主界面.png 截取 x=40~270, y=32~68
|
||
by_geom:
|
||
relative_to: window_top_left
|
||
x_ratio: 0.08 # 左栏中部，约 150px @ 1920w
|
||
y_ratio: 0.05 # 约 55px
|
||
width_ratio: 0.12 # 约 230px
|
||
height_ratio: 0.04 # 约 40px
|
||
threshold: 0.80
|
||
description: "左栏顶部搜索框（未激活状态）"
|
||
|
||
# 截图参考：02-聊天界面.png
|
||
send_button:
|
||
by_image: "wechat_4.0/light/send_button.png"
|
||
# 裁剪建议：截取右下角绿色"发送"按钮，约 60x30
|
||
by_geom:
|
||
relative_to: window_bottom_right
|
||
x_offset: -60
|
||
y_offset: -30
|
||
threshold: 0.85
|
||
require_image: false # 发送按钮不强制图像（geom 兜底足够）
|
||
description: "右下角发送按钮"
|
||
|
||
# 截图参考：02-聊天界面.png
|
||
input_box:
|
||
by_image: "wechat_4.0/light/input_box.png"
|
||
# 裁剪建议：截取底部输入框区域，约 400x50
|
||
by_geom:
|
||
relative_to: window
|
||
x_ratio: 0.65 # 右侧面板中部偏左
|
||
y_ratio: 0.93 # 底部上方
|
||
threshold: 0.75
|
||
description: "聊天输入框"
|
||
|
||
# 用于发送后校验输入框是否清空
|
||
input_box_empty:
|
||
by_image: "wechat_4.0/light/input_box_empty.png"
|
||
by_geom:
|
||
relative_to: window
|
||
x_ratio: 0.65
|
||
y_ratio: 0.93
|
||
threshold: 0.80
|
||
description: "空输入框（发送后校验用）"
|
||
|
||
# 搜索结果第一项，约搜索框下方 70px
|
||
search_result_first:
|
||
by_image: "wechat_4.0/light/search_result_first.png"
|
||
by_geom:
|
||
relative_to: window_top_left
|
||
x_ratio: 0.08
|
||
y_ratio: 0.11 # 约 120px，会话项高度约 70px
|
||
threshold: 0.80
|
||
description: "搜索结果第一项"
|
||
|
||
# 主界面模板（校验是否回到初始空白态）
|
||
# 截图参考：03-主界面.png
|
||
main_view:
|
||
by_image: "wechat_4.0/light/main_view.png"
|
||
# 裁剪建议：截取右侧主区域空白+微信 logo，约 400x300
|
||
by_geom:
|
||
relative_to: window
|
||
x_ratio: 0.65
|
||
y_ratio: 0.50
|
||
threshold: 0.75
|
||
description: "主界面空白态（校验用）"
|
||
|
||
# 高风险操作强制图像命中（阶段 2 后补模板）
|
||
revoke_menu_item:
|
||
by_image: "wechat_4.0/light/revoke_menu_item.png"
|
||
threshold: 0.85
|
||
require_image: true
|
||
```
|
||
|
||
### 4.3 Layer 3 - Action Library
|
||
|
||
```python
|
||
# bridge/ui/actions.py
|
||
class Actions:
|
||
def __init__(self, backend: BackendProtocol, locator: LocatorRegistry):
|
||
self.backend = backend
|
||
self.locator = locator
|
||
|
||
async def find_element(
|
||
self, kind: str, win_geom: WindowGeometry,
|
||
) -> ElementHandle:
|
||
"""按 selector 找元素。优先图像，失败回退几何。
|
||
|
||
高风险操作（require_image=True）图像失败即抛异常。
|
||
"""
|
||
sel = self.locator.get(kind)
|
||
|
||
# 策略1：图像匹配（未熔断时）
|
||
if sel.by_image and not self.locator.is_circuited(kind):
|
||
shot = await self.backend.screenshot()
|
||
roi = (win_geom.x, win_geom.y, win_geom.width, win_geom.height)
|
||
result = await self.backend.find_template(
|
||
shot, sel.by_image, threshold=sel.threshold, roi=roi,
|
||
)
|
||
if result:
|
||
x, y, w, h, conf = result
|
||
self.locator.record_image_success(kind)
|
||
return ElementHandle(
|
||
selector=sel, x=x+w//2, y=y+h//2, w=w, h=h,
|
||
confidence=conf, strategy="image",
|
||
)
|
||
# 图像失败
|
||
self.locator.record_image_failure(kind)
|
||
logger.warning("[action] 图像匹配失败 kind=%s conf=%.3f", kind, 0.0)
|
||
|
||
# 高风险操作：图像失败即拒绝
|
||
if sel.require_image:
|
||
raise ElementNotFoundError(
|
||
kind=kind, reason="image_match_failed_require_image",
|
||
)
|
||
logger.warning("[action] 图像匹配失败 kind=%s，回退几何", kind)
|
||
|
||
# 策略2：几何兜底
|
||
return self._geom_find(sel, win_geom)
|
||
|
||
async def click_element(self, kind: str, win_geom: WindowGeometry) -> ElementHandle:
|
||
"""点击元素，返回元素句柄。"""
|
||
elem = await self.find_element(kind, win_geom)
|
||
await self.backend.click(elem.x, elem.y)
|
||
logger.info("[action] click %s at (%d,%d) strategy=%s conf=%.3f",
|
||
kind, elem.x, elem.y, elem.strategy, elem.confidence)
|
||
return elem
|
||
|
||
async def type_into(self, kind: str, text: str, win_geom: WindowGeometry,
|
||
clear_first: bool = True) -> None:
|
||
"""点击元素 + 清空 + 输入文本。"""
|
||
await self.click_element(kind, win_geom)
|
||
if clear_first:
|
||
await self.backend.key_press("BackSpace", repeat=30)
|
||
await self.backend.type_text(text)
|
||
|
||
async def wait_for(self, kind: str, win_geom: WindowGeometry,
|
||
timeout: float = 5.0, interval: float = 0.3) -> Optional[ElementHandle]:
|
||
"""轮询等待某元素出现。"""
|
||
deadline = time.monotonic() + timeout
|
||
while time.monotonic() < deadline:
|
||
try:
|
||
elem = await self.find_element(kind, win_geom)
|
||
if elem:
|
||
return elem
|
||
except ElementNotFoundError:
|
||
pass
|
||
await asyncio.sleep(interval)
|
||
return None
|
||
|
||
async def screenshot(self) -> bytes:
|
||
return await self.backend.screenshot()
|
||
```
|
||
|
||
### 4.4 Layer 4 - Flow State Machine
|
||
|
||
**最关键的架构升级**。含启动清场、post_verify、安全重置。
|
||
|
||
#### 4.4.1 状态定义
|
||
|
||
```python
|
||
# bridge/ui/flow.py
|
||
from enum import Enum
|
||
from dataclasses import dataclass, field
|
||
from typing import Optional
|
||
|
||
class FlowState(Enum):
|
||
INITIAL = "initial"
|
||
WINDOW_ACTIVATED = "window_activated"
|
||
SEARCH_BOX_CLICKED = "search_box_clicked"
|
||
QUERY_TYPED = "query_typed"
|
||
SESSION_OPENED = "session_opened"
|
||
INPUT_FOCUSED = "input_focused"
|
||
TEXT_TYPED = "text_typed"
|
||
SENT = "sent"
|
||
CLEANED_UP = "cleaned_up"
|
||
FAILED = "failed"
|
||
|
||
@dataclass
|
||
class FlowContext:
|
||
"""流程上下文。"""
|
||
to_wxid: str
|
||
content: str
|
||
display_name: str
|
||
client_request_id: str = "" # 幂等键维度
|
||
win_geom: Optional[WindowGeometry] = None
|
||
before_msg_id: int = 0
|
||
local_send_id: str = ""
|
||
verified: bool = False
|
||
image_confidence: float = 0.0 # 供 metric 上报
|
||
|
||
@dataclass
|
||
class FlowResult:
|
||
success: bool
|
||
local_id: str = ""
|
||
verified: bool = False
|
||
skipped: bool = False
|
||
error: str = ""
|
||
error_code: str = ""
|
||
state: str = ""
|
||
image_confidence: float = 0.0
|
||
duration_ms: int = 0
|
||
|
||
class FlowError(Exception):
|
||
"""流程错误基类。"""
|
||
def __init__(self, code: str, message: str, retryable: bool = False):
|
||
self.code = code
|
||
self.message = message
|
||
self.retryable = retryable
|
||
super().__init__(message)
|
||
|
||
class TransientError(FlowError):
|
||
"""瞬时错误，可重试。"""
|
||
def __init__(self, code: str, message: str):
|
||
super().__init__(code, message, retryable=True)
|
||
|
||
class PermanentError(FlowError):
|
||
"""永久错误，不可重试。"""
|
||
def __init__(self, code: str, message: str):
|
||
super().__init__(code, message, retryable=False)
|
||
```
|
||
|
||
#### 4.4.2 Flow 基类（含全量清场 + post_verify）
|
||
|
||
```python
|
||
# bridge/ui/flow.py
|
||
class Flow:
|
||
"""流程基类。"""
|
||
|
||
def __init__(self, actions: Actions, db_reader=None):
|
||
self.actions = actions
|
||
self.db = db_reader
|
||
# 注意：不加 asyncio.Lock，串行性由 send_queue 保证
|
||
|
||
async def _reset_to_idle(self, win_geom: Optional[WindowGeometry]) -> bool:
|
||
"""安全重置到 IDLE 状态。
|
||
|
||
多策略清场：
|
||
1. Esc×3（关多级菜单）
|
||
2. 点击窗口空白区域（退 webview 焦点）
|
||
3. BackSpace×30（清搜索框）
|
||
4. Esc×2（关残留弹窗）
|
||
5. 截图校验"主界面"，失败返回 False
|
||
|
||
幂等：重复调用无副作用。
|
||
失败不抛异常（吞掉原始错误），返回 False 表示未恢复。
|
||
"""
|
||
try:
|
||
for _ in range(3):
|
||
await self.actions.backend.key_press("Escape")
|
||
await asyncio.sleep(0.3)
|
||
# 点击窗口左上角空白区域（退 webview 焦点）
|
||
if win_geom:
|
||
await self.actions.backend.click(win_geom.x + 10, win_geom.y + 10)
|
||
await asyncio.sleep(0.3)
|
||
await self.actions.backend.key_press("BackSpace", repeat=30)
|
||
await asyncio.sleep(0.3)
|
||
for _ in range(2):
|
||
await self.actions.backend.key_press("Escape")
|
||
await asyncio.sleep(0.3)
|
||
# 截图校验：是否回到主界面
|
||
# 如果有 main_view.png 模板，匹配它
|
||
return await self._verify_main_view(win_geom)
|
||
except Exception as e:
|
||
logger.error("[flow] _reset_to_idle 异常: %s", e)
|
||
return False
|
||
|
||
async def _verify_main_view(self, win_geom: Optional[WindowGeometry]) -> bool:
|
||
"""校验是否回到主界面（匹配 main_view 模板）。"""
|
||
try:
|
||
elem = await self.actions.wait_for("main_view", win_geom, timeout=2.0)
|
||
return elem is not None
|
||
except Exception:
|
||
# 无模板时降级为 True（不阻塞流程）
|
||
return True
|
||
|
||
async def _full_cleanup_on_startup(self) -> bool:
|
||
"""bridge 启动时的全量清场。
|
||
|
||
上次崩溃可能残留脏状态。连续重置 3 次，仍失败则告警。
|
||
"""
|
||
win_geom = None
|
||
try:
|
||
win_geom = await self.actions.backend.get_window_geometry("微信")
|
||
except Exception:
|
||
logger.warning("[flow] 启动清场：微信窗口未找到，跳过")
|
||
return True # 窗口都没有，无需清场
|
||
|
||
for attempt in range(3):
|
||
if await self._reset_to_idle(win_geom):
|
||
logger.info("[flow] 启动清场成功 (attempt=%d)", attempt + 1)
|
||
return True
|
||
logger.warning("[flow] 启动清场失败 (attempt=%d)", attempt + 1)
|
||
|
||
logger.error("[flow] 启动清场 3 次失败，可能需要人工 VNC 接入")
|
||
return False
|
||
```
|
||
|
||
#### 4.4.3 SendTextFlow 实现
|
||
|
||
```python
|
||
# bridge/ui/flows/send_text.py
|
||
class SendTextFlow(Flow):
|
||
"""发文本流程的状态机。"""
|
||
|
||
async def run(self, ctx: FlowContext) -> FlowResult:
|
||
t_start = time.perf_counter()
|
||
state = FlowState.INITIAL
|
||
try:
|
||
# 整流程超时保护（L3）
|
||
async with asyncio.timeout(_FLOW_TIMEOUT_SEC):
|
||
state = await self._activate(ctx)
|
||
state = await self._click_search_box(ctx)
|
||
state = await self._type_query(ctx)
|
||
state = await self._open_session(ctx)
|
||
state = await self._focus_input(ctx)
|
||
state = await self._type_content(ctx)
|
||
state = await self._send(ctx)
|
||
state = await self._cleanup(ctx)
|
||
|
||
return FlowResult(
|
||
success=True,
|
||
local_id=ctx.local_send_id,
|
||
verified=ctx.verified,
|
||
state=state.value,
|
||
image_confidence=ctx.image_confidence,
|
||
duration_ms=int((time.perf_counter() - t_start) * 1000),
|
||
)
|
||
except FlowError as e:
|
||
logger.error("[flow] 失败 state=%s code=%s err=%s", state.value, e.code, e.message)
|
||
# 失败后重置（不阻塞原始错误传播）
|
||
await self._reset_to_idle(ctx.win_geom)
|
||
return FlowResult(
|
||
success=False,
|
||
error=e.message,
|
||
error_code=e.code,
|
||
state=state.value,
|
||
duration_ms=int((time.perf_counter() - t_start) * 1000),
|
||
)
|
||
except asyncio.TimeoutError:
|
||
logger.error("[flow] 整流程超时 state=%s", state.value)
|
||
await self._reset_to_idle(ctx.win_geom)
|
||
return FlowResult(
|
||
success=False,
|
||
error="整流程超时",
|
||
error_code="SEND_TIMEOUT",
|
||
state=state.value,
|
||
duration_ms=int((time.perf_counter() - t_start) * 1000),
|
||
)
|
||
|
||
async def _activate(self, ctx: FlowContext) -> FlowState:
|
||
await self.actions.backend.activate_window("微信")
|
||
await asyncio.sleep(1.0)
|
||
ctx.win_geom = await self.actions.backend.get_window_geometry("微信")
|
||
await self.actions.backend.key_press("Escape")
|
||
await asyncio.sleep(0.5)
|
||
return FlowState.WINDOW_ACTIVATED
|
||
|
||
async def _click_search_box(self, ctx: FlowContext) -> FlowState:
|
||
await self.actions.click_element("search_box", ctx.win_geom)
|
||
await asyncio.sleep(1.0)
|
||
return FlowState.SEARCH_BOX_CLICKED
|
||
|
||
async def _type_query(self, ctx: FlowContext) -> FlowState:
|
||
await self.actions.backend.key_press("BackSpace", repeat=30)
|
||
await asyncio.sleep(0.5)
|
||
await self.actions.backend.type_text(ctx.display_name)
|
||
await asyncio.sleep(1.0)
|
||
return FlowState.QUERY_TYPED
|
||
|
||
async def _open_session(self, ctx: FlowContext) -> FlowState:
|
||
# 点击搜索结果第一项（用 geom 兜底，图像匹配不强求）
|
||
result_y = ctx.win_geom.y + 120
|
||
await self.actions.backend.click(ctx.win_geom.x + 150, result_y)
|
||
await asyncio.sleep(1.0)
|
||
await self.actions.backend.key_press("Escape")
|
||
await asyncio.sleep(0.5)
|
||
return FlowState.SESSION_OPENED
|
||
|
||
async def _focus_input(self, ctx: FlowContext) -> FlowState:
|
||
await self.actions.click_element("input_box", ctx.win_geom)
|
||
await asyncio.sleep(0.3)
|
||
return FlowState.INPUT_FOCUSED
|
||
|
||
async def _type_content(self, ctx: FlowContext) -> FlowState:
|
||
await self.actions.backend.type_text(ctx.content)
|
||
await asyncio.sleep(1.0)
|
||
return FlowState.TEXT_TYPED
|
||
|
||
async def _send(self, ctx: FlowContext) -> FlowState:
|
||
# 记录发送前的 DB 最新 msg_id
|
||
if self.db:
|
||
try:
|
||
ctx.before_msg_id = await self.db.get_latest_msg_id(ctx.to_wxid)
|
||
except Exception:
|
||
ctx.before_msg_id = 0
|
||
|
||
# 点击发送按钮
|
||
elem = await self.actions.click_element("send_button", ctx.win_geom)
|
||
ctx.image_confidence = max(ctx.image_confidence, elem.confidence)
|
||
await asyncio.sleep(1.0)
|
||
|
||
# 校验：DB 是否出现新消息
|
||
ctx.verified = await self._verify_sent(ctx)
|
||
ctx.local_send_id = f"local_{int(time.time())}_{random.randint(0, 0xFFFFFF):06x}"
|
||
return FlowState.SENT
|
||
|
||
async def _verify_sent(self, ctx: FlowContext) -> bool:
|
||
"""发送后校验，5 秒窗口内 DB 必须出现新消息。
|
||
|
||
关键：必须验证 talker == to_wxid，防止 display_name 串号。
|
||
"""
|
||
if not self.db or ctx.before_msg_id == 0:
|
||
return await self._verify_by_screenshot(ctx)
|
||
|
||
deadline = time.monotonic() + 5.0
|
||
while time.monotonic() < deadline:
|
||
msgs = await self.db.get_messages(
|
||
ctx.to_wxid, limit=1, after_local_id=ctx.before_msg_id,
|
||
)
|
||
if msgs:
|
||
msg = msgs[0]
|
||
# 关键校验：talker 必须匹配 + 内容必须匹配 + is_sender=True
|
||
if (msg.talker == ctx.to_wxid
|
||
and msg.content == ctx.content
|
||
and msg.is_sender):
|
||
return True
|
||
await asyncio.sleep(0.5)
|
||
return False
|
||
|
||
async def _verify_by_screenshot(self, ctx: FlowContext) -> bool:
|
||
"""降级校验：截图匹配空输入框模板。"""
|
||
try:
|
||
elem = await self.actions.wait_for(
|
||
"input_box_empty", ctx.win_geom, timeout=2.0,
|
||
)
|
||
return elem is not None
|
||
except Exception:
|
||
return False
|
||
|
||
async def _cleanup(self, ctx: FlowContext) -> FlowState:
|
||
await self.actions.backend.key_press("Escape")
|
||
await asyncio.sleep(0.5)
|
||
return FlowState.CLEANED_UP
|
||
```
|
||
|
||
### 4.5 Layer 5 - Flow Orchestrator（含幂等 + 熔断 + 重试）
|
||
|
||
#### 4.5.1 幂等缓存（含 client_request_id）
|
||
|
||
```python
|
||
# bridge/ui/idem_cache.py
|
||
import hashlib
|
||
import time
|
||
from typing import Any, Optional
|
||
from collections import OrderedDict
|
||
|
||
class IdemCache:
|
||
"""内存短时去重，TTL=300s（5 分钟）。
|
||
|
||
幂等键 = (flow_name, to_wxid, content_hash, client_request_id)
|
||
- client_request_id 非空时：调用方换 id 即可重发
|
||
- client_request_id 为空时：纯 to_wxid + content_hash 去重（旧调用方兼容）
|
||
"""
|
||
|
||
def __init__(self, ttl: int = 300, max_size: int = 1000):
|
||
self.ttl = ttl
|
||
self._cache: OrderedDict[str, tuple[Any, float]] = OrderedDict()
|
||
self._max_size = max_size
|
||
|
||
def _make_key(self, flow_name: str, to_wxid: str, content: str,
|
||
client_request_id: str = "") -> str:
|
||
# 用完整 SHA256，不截断（避免短消息碰撞）
|
||
content_hash = hashlib.sha256(content.encode()).hexdigest()
|
||
return f"{flow_name}:{to_wxid}:{content_hash}:{client_request_id}"
|
||
|
||
def get(self, key: str) -> Optional[Any]:
|
||
if key in self._cache:
|
||
val, ts = self._cache[key]
|
||
if time.monotonic() - ts < self.ttl:
|
||
self._cache.move_to_end(key)
|
||
return val
|
||
del self._cache[key]
|
||
return None
|
||
|
||
def set(self, key: str, val: Any) -> None:
|
||
self._cache[key] = (val, time.monotonic())
|
||
if len(self._cache) > self._max_size:
|
||
self._cache.popitem(last=False) # LRU 淘汰
|
||
|
||
def clear(self) -> None:
|
||
"""bridge 重启时清空（内存缓存不持久化）。"""
|
||
self._cache.clear()
|
||
```
|
||
|
||
#### 4.5.2 熔断器
|
||
|
||
```python
|
||
# bridge/ui/circuit_breaker.py
|
||
import time
|
||
from enum import Enum
|
||
|
||
class CircuitState(Enum):
|
||
CLOSED = "closed" # 正常
|
||
OPEN = "open" # 熔断，拒绝请求
|
||
HALF_OPEN = "half_open" # 半开，试探
|
||
|
||
class CircuitBreaker:
|
||
"""通用熔断器。
|
||
|
||
连续失败 N 次开熔断，冷却期后半开试探，成功则关闭。
|
||
"""
|
||
|
||
def __init__(self, name: str, failure_threshold: int = 5,
|
||
recovery_timeout: int = 30):
|
||
self.name = name
|
||
self.failure_threshold = failure_threshold
|
||
self.recovery_timeout = recovery_timeout
|
||
self._failures = 0
|
||
self._state = CircuitState.CLOSED
|
||
self._opened_at = 0.0
|
||
|
||
@property
|
||
def state(self) -> CircuitState:
|
||
if self._state == CircuitState.OPEN:
|
||
if time.monotonic() - self._opened_at >= self.recovery_timeout:
|
||
self._state = CircuitState.HALF_OPEN
|
||
logger.info("[circuit] %s 进入半开状态", self.name)
|
||
return self._state
|
||
|
||
def allow(self) -> bool:
|
||
"""是否允许通过。"""
|
||
return self.state in (CircuitState.CLOSED, CircuitState.HALF_OPEN)
|
||
|
||
def record_success(self) -> None:
|
||
if self._state == CircuitState.HALF_OPEN:
|
||
logger.info("[circuit] %s 半开试探成功，关闭熔断", self.name)
|
||
self._failures = 0
|
||
self._state = CircuitState.CLOSED
|
||
|
||
def record_failure(self) -> None:
|
||
self._failures += 1
|
||
if self._failures >= self.failure_threshold:
|
||
self._state = CircuitState.OPEN
|
||
self._opened_at = time.monotonic()
|
||
logger.warning("[circuit] %s 熔断开启（失败 %d 次）", self.name, self._failures)
|
||
```
|
||
|
||
#### 4.5.3 FlowOrchestrator
|
||
|
||
```python
|
||
# bridge/ui/orchestrator.py
|
||
class FlowOrchestrator:
|
||
"""管理所有 UI 流程的编排、幂等、重试、熔断。"""
|
||
|
||
def __init__(self, send_queue: SendQueue, idem_cache: IdemCache,
|
||
actions: Actions, db_reader=None):
|
||
self.send_queue = send_queue
|
||
self.idem_cache = idem_cache
|
||
self.actions = actions
|
||
self.db = db_reader
|
||
# DB 校验熔断器：连续失败 5 次熔断 30s
|
||
self.db_verify_breaker = CircuitBreaker("db_verify", 5, 30)
|
||
|
||
async def send_text(self, to_wxid: str, content: str,
|
||
display_name: str = None,
|
||
client_request_id: str = "") -> FlowResult:
|
||
# 1. 幂等检查
|
||
idem_key = self.idem_cache._make_key(
|
||
"send_text", to_wxid, content, client_request_id,
|
||
)
|
||
cached = self.idem_cache.get(idem_key)
|
||
if cached:
|
||
logger.info("[orch] 跳过重复发送 idem_key=%s", idem_key[:32])
|
||
return FlowResult(
|
||
success=True, local_id=cached, verified=True,
|
||
skipped=True, state="idempotent_skip",
|
||
)
|
||
|
||
# 2. 入队串行执行
|
||
async def _run():
|
||
flow = SendTextFlow(self.actions, self.db)
|
||
ctx = FlowContext(
|
||
to_wxid=to_wxid, content=content,
|
||
display_name=display_name or to_wxid,
|
||
client_request_id=client_request_id,
|
||
)
|
||
return await flow.run(ctx)
|
||
|
||
try:
|
||
result = await self.send_queue.enqueue(_run)
|
||
except BridgeError as e:
|
||
if e.code == "RATE_LIMITED":
|
||
return FlowResult(
|
||
success=False, error=e.message, error_code="RATE_LIMITED",
|
||
state="rate_limited",
|
||
)
|
||
raise
|
||
|
||
# 3. 成功才写幂等缓存
|
||
if result.success and result.verified:
|
||
self.idem_cache.set(idem_key, result.local_id)
|
||
|
||
# 4. DB 校验熔断
|
||
if not result.verified:
|
||
self.db_verify_breaker.record_failure()
|
||
else:
|
||
self.db_verify_breaker.record_success()
|
||
|
||
return result
|
||
```
|
||
|
||
### 4.6 Layer 6 - Capability API
|
||
|
||
```python
|
||
# bridge/ui/capabilities.py
|
||
from dataclasses import dataclass
|
||
from typing import Optional
|
||
|
||
@dataclass
|
||
class SendResult:
|
||
"""对调用方的稳定响应。"""
|
||
success: bool # 发送动作是否完成
|
||
local_id: str = ""
|
||
verified: bool = False # DB 校验是否通过
|
||
skipped: bool = False # 是否因幂等跳过
|
||
error: str = ""
|
||
error_code: str = "" # 错误分类（见错误码表）
|
||
retryable: bool = False # 是否可重试
|
||
diagnostics: dict = None # 置信度、耗时等诊断信息
|
||
|
||
class WeChatCapabilities:
|
||
"""对外稳定的业务接口，与底层后端完全解耦。"""
|
||
|
||
def __init__(self, orchestrator: FlowOrchestrator):
|
||
self.orch = orchestrator
|
||
|
||
async def send_text(self, to_wxid: str, content: str,
|
||
display_name: str = None,
|
||
client_request_id: str = "") -> SendResult:
|
||
result = await self.orch.send_text(
|
||
to_wxid, content, display_name, client_request_id,
|
||
)
|
||
return SendResult(
|
||
success=result.success,
|
||
local_id=result.local_id,
|
||
verified=result.verified,
|
||
skipped=result.skipped,
|
||
error=result.error,
|
||
error_code=result.error_code,
|
||
retryable=result.error_code in RETRYABLE_CODES,
|
||
diagnostics={
|
||
"image_confidence": result.image_confidence,
|
||
"duration_ms": result.duration_ms,
|
||
"state": result.state,
|
||
},
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 五、横切高可用模块
|
||
|
||
### 5.1 错误码分类表
|
||
|
||
```python
|
||
# bridge/ui/errors.py
|
||
|
||
# 可重试错误（瞬时性，重试可能成功）
|
||
RETRYABLE_CODES = {
|
||
"RATE_LIMITED", # 队列限流
|
||
"SEND_TIMEOUT", # xdotool 超时
|
||
"STATE_DIRTY", # 状态机脏状态，重置后可重试
|
||
"X11_TEMP_UNAVAILABLE", # X11 临时不可用
|
||
}
|
||
|
||
# 不可重试错误（永久性，重试无意义）
|
||
NON_RETRYABLE_CODES = {
|
||
"WECHAT_NOT_LOGGED_IN", # 需人工扫码
|
||
"WINDOW_NOT_FOUND", # 微信未运行
|
||
"ELEMENT_NOT_FOUND", # 模板失效，需更新模板
|
||
"DB_VERIFY_FAILED", # 消息可能已发到错会话，需人工排查
|
||
"AMBIGUOUS_CONTACT", # 重名联系人，需指定更精确 display_name
|
||
"X11_UNAVAILABLE", # Xvnc 崩溃，需重启容器
|
||
"BRIDGE_CIRCUITED", # 熔断中
|
||
}
|
||
|
||
# 特殊：DB_VERIFY_FAILED 不可重试
|
||
# 理由：消息可能已发出，重试就是重复。调用方应人工排查或等幂等窗口过期。
|
||
```
|
||
|
||
### 5.2 重试策略
|
||
|
||
```python
|
||
# bridge/ui/retry.py
|
||
import random
|
||
|
||
class RetryPolicy:
|
||
"""重试策略：指数退避 + 抖动。"""
|
||
|
||
def __init__(self, max_attempts: int = 2, base_delay: float = 1.0,
|
||
max_delay: float = 30.0):
|
||
self.max_attempts = max_attempts # UI 自动化最多重试 1 次（不含首次）
|
||
self.base_delay = base_delay
|
||
self.max_delay = max_delay
|
||
|
||
def get_delay(self, attempt: int) -> float:
|
||
"""指数退避 + 抖动。"""
|
||
delay = min(self.base_delay * (2 ** attempt), self.max_delay)
|
||
# 抖动 ±25%，避免多调用方同步重试
|
||
jitter = delay * 0.25 * random.uniform(-1, 1)
|
||
return delay + jitter
|
||
|
||
def should_retry(self, error_code: str, attempt: int) -> bool:
|
||
"""是否应该重试。"""
|
||
if attempt >= self.max_attempts:
|
||
return False
|
||
return error_code in RETRYABLE_CODES
|
||
```
|
||
|
||
**关键决策**：
|
||
- UI 自动化**最多重试 1 次**（不是 3 次）——重试多了反而容易把状态搞更乱
|
||
- 重试前必须 `_reset_to_idle` + 截图校验
|
||
- `DB_VERIFY_FAILED` 不可重试，避免重复发送
|
||
- `RATE_LIMITED` 按 `retry_after` 等待，不用指数退避
|
||
|
||
### 5.3 Watchdog（崩溃感知）
|
||
|
||
```python
|
||
# bridge/ui/watchdog.py
|
||
class WeChatWatchdog:
|
||
"""后台监控微信与 Xvnc 进程，崩溃主动恢复。"""
|
||
|
||
def __init__(self, backend: XdotoolBackend, interval: float = 10.0):
|
||
self.backend = backend
|
||
self.interval = interval
|
||
self._task: Optional[asyncio.Task] = None
|
||
self._consecutive_failures = 0
|
||
|
||
async def start(self) -> None:
|
||
if self._task is None or self._task.done():
|
||
self._task = asyncio.create_task(self._run())
|
||
|
||
async def stop(self) -> None:
|
||
if self._task and not self._task.done():
|
||
self._task.cancel()
|
||
try:
|
||
await self._task
|
||
except asyncio.CancelledError:
|
||
pass
|
||
|
||
async def _run(self) -> None:
|
||
"""每 10s 检查一次。"""
|
||
while True:
|
||
try:
|
||
await asyncio.sleep(self.interval)
|
||
await self._check()
|
||
except asyncio.CancelledError:
|
||
break
|
||
except Exception as e:
|
||
logger.error("[watchdog] 检查异常: %s", e)
|
||
|
||
async def _check(self) -> None:
|
||
# 1. 检查微信进程
|
||
running = await self._is_wechat_running()
|
||
if not running:
|
||
self._consecutive_failures += 1
|
||
if self._consecutive_failures >= 2:
|
||
logger.warning("[watchdog] 微信连续 2 次检测失败，触发 autofix")
|
||
await self._autofix_wechat()
|
||
else:
|
||
self._consecutive_failures = 0
|
||
|
||
# 2. 检查 X11 server（Xvnc）
|
||
if not await self._is_x11_available():
|
||
logger.error("[watchdog] X11 不可用，Xvnc 可能崩溃")
|
||
# Xvnc 崩溃 bridge 无法自救，告警
|
||
# 容器层 s6 会自动重启 Xvnc
|
||
|
||
async def _is_wechat_running(self) -> bool:
|
||
try:
|
||
rc, stdout, _ = await self.backend._run(["pgrep", "-x", "wechat"])
|
||
return rc == 0 and bool(stdout.decode(errors="ignore").strip())
|
||
except Exception:
|
||
return False
|
||
|
||
async def _is_x11_available(self) -> bool:
|
||
try:
|
||
# 检查 X11 socket + xdpyinfo 探测
|
||
rc, _, _ = await self.backend._run(["xdpyinfo", "-display", self.backend.display])
|
||
return rc == 0
|
||
except Exception:
|
||
return False
|
||
|
||
async def _autofix_wechat(self) -> None:
|
||
"""触发微信 autofix：pkill → autostart 拉起 → bridge 兜底启动。"""
|
||
try:
|
||
await self.backend._run(["pkill", "-x", "wechat"])
|
||
await asyncio.sleep(2.0)
|
||
# autostart 会自动拉起，bridge 兜底
|
||
# 复用现有 start_wechat 逻辑
|
||
except Exception as e:
|
||
logger.error("[watchdog] autofix 失败: %s", e)
|
||
```
|
||
|
||
### 5.4 ResourceReaper（资源回收）
|
||
|
||
```python
|
||
# bridge/ui/resource_reaper.py
|
||
import os
|
||
import time
|
||
import glob
|
||
|
||
class ResourceReaper:
|
||
"""定期清理临时资源。"""
|
||
|
||
def __init__(self, debug_screenshot_dir: str = "/tmp/woc_debug",
|
||
max_age_hours: int = 24, max_total_mb: int = 100):
|
||
self.debug_dir = debug_screenshot_dir
|
||
self.max_age_hours = max_age_hours
|
||
self.max_total_mb = max_total_mb
|
||
self._task: Optional[asyncio.Task] = None
|
||
|
||
async def start(self) -> None:
|
||
if self._task is None or self._task.done():
|
||
self._task = asyncio.create_task(self._run())
|
||
|
||
async def _run(self) -> None:
|
||
"""每小时清理一次。"""
|
||
while True:
|
||
try:
|
||
await asyncio.sleep(3600)
|
||
await self.cleanup()
|
||
except asyncio.CancelledError:
|
||
break
|
||
except Exception as e:
|
||
logger.error("[reaper] 清理异常: %s", e)
|
||
|
||
async def cleanup(self) -> None:
|
||
"""清理过期调试截图 + 总量超限时 LRU 删除。"""
|
||
if not os.path.exists(self.debug_dir):
|
||
return
|
||
|
||
now = time.time()
|
||
max_age_sec = self.max_age_hours * 3600
|
||
|
||
# 1. 删除超龄文件
|
||
for f in glob.glob(os.path.join(self.debug_dir, "*.png")):
|
||
try:
|
||
mtime = os.path.getmtime(f)
|
||
if now - mtime > max_age_sec:
|
||
os.remove(f)
|
||
logger.debug("[reaper] 删除过期文件: %s", f)
|
||
except OSError:
|
||
pass
|
||
|
||
# 2. 总量超限时 LRU 删除
|
||
files = [(f, os.path.getmtime(f))
|
||
for f in glob.glob(os.path.join(self.debug_dir, "*.png"))]
|
||
files.sort(key=lambda x: x[1]) # 按修改时间排序
|
||
|
||
total_mb = sum(os.path.getsize(f) for f, _ in files) / (1024 * 1024)
|
||
while total_mb > self.max_total_mb and files:
|
||
f, _ = files.pop(0) # 删最老的
|
||
try:
|
||
os.remove(f)
|
||
total_mb -= os.path.getsize(f) / (1024 * 1024)
|
||
except OSError:
|
||
pass
|
||
```
|
||
|
||
### 5.5 Metrics（Prometheus）
|
||
|
||
```python
|
||
# bridge/ui/metrics.py
|
||
from prometheus_client import Counter, Histogram, Gauge
|
||
|
||
# 发送计数
|
||
send_total = Counter(
|
||
"woc_send_total", "Total send operations",
|
||
["result"], # success / failed / skipped
|
||
)
|
||
|
||
# 发送耗时
|
||
send_duration = Histogram(
|
||
"woc_send_duration_seconds", "Send duration",
|
||
buckets=[0.5, 1, 2, 5, 10, 15, 30, 60],
|
||
)
|
||
|
||
# 失败状态分布
|
||
send_failed_by_state = Counter(
|
||
"woc_send_failed_by_state_total", "Failed sends by state",
|
||
["state"], # window_activated / search_box_clicked / ...
|
||
)
|
||
|
||
# 图像匹配置信度
|
||
image_match_confidence = Histogram(
|
||
"woc_image_match_confidence", "Image match confidence",
|
||
buckets=[0.5, 0.7, 0.8, 0.85, 0.9, 0.95, 1.0],
|
||
)
|
||
|
||
# DB 校验耗时
|
||
db_verify_duration = Histogram(
|
||
"woc_db_verify_duration_seconds", "DB verify duration",
|
||
buckets=[0.1, 0.5, 1, 2, 5, 10],
|
||
)
|
||
|
||
# 队列深度
|
||
send_queue_pending = Gauge(
|
||
"woc_send_queue_pending", "Send queue pending count",
|
||
)
|
||
|
||
# 微信运行状态
|
||
wechat_running = Gauge(
|
||
"woc_wechat_running", "WeChat process running (0/1)",
|
||
)
|
||
|
||
# 熔断状态
|
||
circuit_state = Gauge(
|
||
"woc_circuit_state", "Circuit breaker state (0=closed, 1=open, 2=half)",
|
||
["name"],
|
||
)
|
||
```
|
||
|
||
### 5.6 TraceID
|
||
|
||
```python
|
||
# bridge/ui/trace.py
|
||
import uuid
|
||
from contextvars import ContextVar
|
||
|
||
# 贯穿单次请求的所有日志行
|
||
trace_id_var: ContextVar[str] = ContextVar("trace_id", default="")
|
||
|
||
def new_trace_id() -> str:
|
||
tid = uuid.uuid4().hex[:12]
|
||
trace_id_var.set(tid)
|
||
return tid
|
||
|
||
def get_trace_id() -> str:
|
||
return trace_id_var.get()
|
||
|
||
# 日志格式中加入 trace_id
|
||
class TraceFilter(logging.Filter):
|
||
def filter(self, record):
|
||
record.trace_id = get_trace_id()
|
||
return True
|
||
```
|
||
|
||
---
|
||
|
||
## 六、目录结构重构
|
||
|
||
```
|
||
bridge/woc_bridge/
|
||
├── ui/
|
||
│ ├── __init__.py
|
||
│ ├── backends/ # Layer 1
|
||
│ │ ├── __init__.py
|
||
│ │ ├── base.py # BackendProtocol + WindowGeometry
|
||
│ │ ├── xdotool.py # XdotoolBackend（含超时/取消安全）
|
||
│ │ └── opencv.py # OpenCVBackend（含 LRU 缓存）
|
||
│ ├── locators/ # Layer 2
|
||
│ │ ├── __init__.py
|
||
│ │ ├── base.py # Selector + ElementHandle + GeomSpec
|
||
│ │ └── registry.py # LocatorRegistry（含熔断）
|
||
│ ├── actions.py # Layer 3
|
||
│ ├── flow.py # Layer 4 基类
|
||
│ ├── flows/ # Layer 4 具体流程
|
||
│ │ ├── __init__.py
|
||
│ │ └── send_text.py
|
||
│ ├── orchestrator.py # Layer 5
|
||
│ ├── idem_cache.py # 幂等缓存
|
||
│ ├── circuit_breaker.py # 熔断器
|
||
│ ├── retry.py # 重试策略
|
||
│ ├── errors.py # 错误码分类
|
||
│ ├── capabilities.py # Layer 6 对外接口
|
||
│ ├── watchdog.py # HA: 崩溃感知
|
||
│ ├── resource_reaper.py # HA: 资源回收
|
||
│ ├── metrics.py # HA: Prometheus
|
||
│ ├── trace.py # HA: TraceID
|
||
│ ├── profiles/ # UI 元素配置
|
||
│ │ ├── default.yaml
|
||
│ │ ├── wechat_4.0_1920x1080.yaml
|
||
│ │ └── templates/
|
||
│ │ └── wechat_4.0/
|
||
│ │ ├── light/ # 浅色模式模板
|
||
│ │ │ ├── search_box.png
|
||
│ │ │ ├── send_button.png
|
||
│ │ │ ├── input_box.png
|
||
│ │ │ ├── input_box_empty.png
|
||
│ │ │ └── main_view.png # 主界面模板（校验用）
|
||
│ │ └── dark/ # 深色模式模板（阶段 2 补）
|
||
│ ├── qr_capture.py # 保留（不变）
|
||
│ └── xdotool_driver.py # 旧文件保留作兼容层
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 七、最小可行实现（MVP）路径
|
||
|
||
**核心原则**：每个阶段都可独立交付，每个阶段都有可见收益，不允许大爆炸式重构。
|
||
|
||
### 阶段 0：PoC 验证（先验证假设）
|
||
|
||
#### PoC 1：OpenCV 模板匹配可行性
|
||
- 容器内手动截微信主界面（搜索框、发送按钮、输入框各一张）
|
||
- **或直接使用用户已提供的截图**：`03-主界面.png`（搜索框）、`02-聊天界面.png`（发送按钮/输入框）
|
||
- 写 50 行 Python 脚本，用 `cv2.matchTemplate` 验证能否稳定命中
|
||
- 测试不同分辨率下的匹配度（1280x720 / 1920x1080）
|
||
- **关键**：`search_box.png` 模板必须从未激活搜索框截取，不可用带下拉覆盖层的图
|
||
- **判定标准**：阈值 0.80 时命中率 > 95%，多尺度匹配下命中位置误差 < 5px
|
||
|
||
#### PoC 2：状态机回滚可行性
|
||
- 把现有 `send_text` 拆成 5 个状态
|
||
- 在中间状态故意失败（模拟 `click_element` 返回 None）
|
||
- 验证 `_reset_to_idle` 能否把微信 UI 恢复到可用状态
|
||
- **判定标准**：回滚后下一次发送能正常进行，无残留弹窗/搜索框/焦点错位
|
||
|
||
#### PoC 3（可选）：CDP 端口开启可行性
|
||
- 容器内 `ss -tlnp | grep -E "9222|DevTools"` 检查
|
||
- 尝试独立启动 WeChatAppEx 加 `--remote-debugging-port=9222 --user-data-dir=/tmp/wx-debug`
|
||
- `curl http://127.0.0.1:9222/json/version` 看是否返回 JSON
|
||
- **判定标准**：能拿到 `webSocketDebuggerUrl` → CDP 路线可行
|
||
|
||
### 阶段 1：抽象层落地 + P0 高可用修复（行为不变）
|
||
|
||
**目标**：把现有代码包装成六层架构的骨架，**同时修复 P0 高可用问题**，行为完全不变。
|
||
|
||
**任务清单**：
|
||
1. 新建 [bridge/ui/backends/base.py](../bridge/woc_bridge/ui) 定义 `BackendProtocol`
|
||
2. 新建 `backends/xdotool.py` 移植现有方法，**关键改进**：
|
||
- `_CMD_TIMEOUT_SEC` 从 15s 降到 5s
|
||
- `_run` 改为 `_run_managed` 上下文管理器，确保取消时 kill+wait
|
||
- 截图用 `scrot -o -` 输出到 stdout，不写文件
|
||
- 加 `_ui_lock` 保护 UI 单焦点
|
||
3. 新建 `locators/base.py` + `registry.py`
|
||
4. 新建 `actions.py`
|
||
5. 新建 `profiles/default.yaml` 迁移硬编码常量
|
||
6. 新建 `capabilities.py`
|
||
7. **P0 修复**：
|
||
- 生产环境关闭 `_DEBUG_SCREENSHOTS`（环境变量 `WOC_UI_DEBUG_SHOTS=false`）
|
||
- 修复 `_step` 的 `max(1.0, remaining)` 为 `max(_STEP_MIN_TIMEOUT_SEC, remaining)`
|
||
- 启动时执行 `_full_cleanup_on_startup`
|
||
8. **旧 `xdotool_driver.py` 保留**，新代码通过 `capabilities.py` 调用
|
||
|
||
**验收标准**：
|
||
- 现有 `/api/send/text` 接口行为完全不变
|
||
- 调试截图不再写磁盘（或写到 `/tmp/woc_debug/` 并自动清理）
|
||
- 无子进程泄漏（取消时 kill+wait）
|
||
- bridge 启动后微信 UI 处于已知态
|
||
|
||
### 阶段 2：引入图像校验
|
||
|
||
**目标**：在定位层加 OpenCV 图像匹配，点击前校验是否命中正确元素。
|
||
|
||
**任务清单**：
|
||
1. 新建 `backends/opencv.py` 实现 `find_template`（含 LRU 缓存）
|
||
2. 容器内截取微信关键 UI 元素模板，保存到 `profiles/templates/wechat_4.0/light/`
|
||
3. 截取 `main_view.png` 主界面模板（供 `_verify_main_view` 使用）
|
||
4. 修改 `Actions.find_element`：优先图像匹配，失败回退几何
|
||
5. **高风险操作（撤回/删除）强制要求图像命中**（`require_image: true`）
|
||
6. 加 per-kind 熔断（连续 10 次失败熔断 5 分钟）
|
||
|
||
**验收标准**：
|
||
- 1280x720 分辨率下发送文本成功率 > 90%
|
||
- 图像匹配失败时回退到几何定位，不报错
|
||
- 撤回操作在图像未命中时拒绝执行，返回 `ELEMENT_NOT_FOUND`
|
||
- 图像匹配置信度通过 Prometheus metric 暴露
|
||
|
||
### 阶段 3：引入状态机 + DB 校验 + 幂等
|
||
|
||
**目标**：把 `send_text` 重构为状态机，加 DB 回读校验与幂等去重。
|
||
|
||
**任务清单**：
|
||
1. 新建 `flow.py` 定义 `Flow` 基类 + `FlowState` 枚举 + `FlowContext`
|
||
2. 新建 `flows/send_text.py` 实现 `SendTextFlow`（含 post_verify）
|
||
3. 新建 `orchestrator.py` 编排幂等检查 + 入队 + 重试
|
||
4. 新建 `idem_cache.py` 实现内存去重（含 `client_request_id`）
|
||
5. 新建 `circuit_breaker.py` 实现 DB 校验熔断
|
||
6. 新建 `errors.py` 错误码分类
|
||
7. 新建 `retry.py` 重试策略（指数退避 + 抖动，最多 1 次）
|
||
8. 在 `SendTextFlow._send` 中加 DB 校验：
|
||
- **关键**：验证 `msg.talker == to_wxid`（防 display_name 串号）
|
||
- DB 校验失败时区分 `success=true, verified=false` vs `success=false`
|
||
9. 切换 `/api/send/text` 路由到新实现
|
||
10. 新建 `metrics.py` 暴露 Prometheus 指标
|
||
11. 新建 `watchdog.py` 微信/Xvnc 崩溃感知
|
||
12. 新建 `resource_reaper.py` 资源回收
|
||
13. 新建 `trace.py` TraceID
|
||
|
||
**验收标准**：
|
||
- 5 分钟内重复发送相同内容（同 client_request_id）被跳过，返回 `skipped=True`
|
||
- 不同 client_request_id 的相同内容可正常发送
|
||
- 发送失败（DB 校验未通过）时返回 `verified=False`，但不返回 `SEND_FAILED`（调用方不误重试）
|
||
- 发错人时 DB 校验失败（talker 不匹配），返回 `DB_VERIFY_FAILED`（不可重试）
|
||
- 失败后状态机回滚到 IDLE，下一次发送正常
|
||
- Prometheus `/metrics` 端点可查
|
||
- 微信崩溃后 watchdog 10s 内感知并触发 autofix
|
||
|
||
### 阶段 4（可选）：CDP 后端 PoC
|
||
|
||
**目标**：若 PoC 3 验证 CDP 可行，实现 `CDPBackend` 用于朋友圈/小程序/公众号文章。
|
||
|
||
**任务清单**：
|
||
1. 新建 `backends/cdp.py` 用 Playwright `connect_over_cdp` 连接
|
||
2. 实现 `async with` 上下文管理，`__aexit__` 必 `browser.close()`
|
||
3. 加健康检查：每次操作前 `browser.is_connected()`，失败重连
|
||
4. CDP 与 xdotool 共享同一个 `send_queue` 串行（不并发）
|
||
5. page 池上限 5 个，超限拒绝新建
|
||
6. 朋友圈发布流程切换到 CDP
|
||
|
||
**验收标准**：
|
||
- 朋友圈发布成功率 > 90%
|
||
- CDP 连接断开后自动重连
|
||
- 无 page 泄漏（`cdp_pages_active` < 5）
|
||
|
||
### 阶段 5：多应用桥接框架对齐
|
||
|
||
**目标**：把 `WechatDriver` 改造为实现 [多应用桥接框架设计.md](./多应用桥接框架设计.md) 定义的 `AppDriver` 抽象。
|
||
|
||
**任务清单**：
|
||
1. 抽象 `AppDriver` 接口
|
||
2. `WechatDriver` 实现该接口
|
||
3. 落地 `AppKindRegistry` / `AppInstance` / `BridgeContext`
|
||
4. `AppState` 改为 per-instance（支持多实例 X server 隔离）
|
||
5. 新增应用（如 Telegram/Chromium）时复用通用层
|
||
|
||
---
|
||
|
||
## 八、关键工程决策汇总
|
||
|
||
### 8.1 并发模型
|
||
- **串行化只在 `send_queue` 一层**，Flow 内部不加锁（避免双重阻塞）
|
||
- 只读探测走队列外快速路径，但共享 `_ui_lock` 与发送互斥
|
||
- 多实例需独立 X server（阶段 5）
|
||
|
||
### 8.2 超时层级（解决 L1/L2 冲突）
|
||
- L1 单命令：`_CMD_TIMEOUT_SEC=5s`（从 15s 降到 5s）
|
||
- L2 单步骤：`max(_STEP_MIN_TIMEOUT_SEC=7s, remaining)`（确保 ≥ L1+2s）
|
||
- L3 整流程：`_FLOW_TIMEOUT_SEC=30s`
|
||
- L4 HTTP 请求：`_HTTP_TIMEOUT_SEC=60s`
|
||
|
||
### 8.3 子进程安全
|
||
- `_run_managed` 上下文管理器：任何取消/超时/异常都 kill+wait
|
||
- 所有 `create_subprocess_exec` 必须显式 `stdout=PIPE/DEVNULL`，禁止默认继承
|
||
|
||
### 8.4 资源回收
|
||
- 调试截图：生产环境关闭，调试模式写 `/tmp/woc_debug/`，每小时清理 + 100MB 上限
|
||
- 模板缓存：LRU 上限 20 个（约 40MB）
|
||
- OpenCV ndarray：多尺度逐个处理 + 显式 `del`
|
||
- Playwright page：`async with` + 池上限 5
|
||
|
||
### 8.5 熔断策略
|
||
- DB 校验熔断：连续失败 5 次熔断 30s，半开试探
|
||
- 图像匹配熔断：per-kind 连续 10 次失败熔断 5 分钟
|
||
- 熔断后降级：DB → 截图校验；图像 → 几何坐标（高风险操作不降级）
|
||
|
||
### 8.6 幂等设计
|
||
- 幂等键 = `(flow_name, to_wxid, content_sha256, client_request_id)`
|
||
- 用完整 SHA256，不截断（避免短消息碰撞）
|
||
- 5 分钟 TTL
|
||
- 内存缓存不持久化，bridge 重启丢失（可接受，重启不频繁）
|
||
- **关键**：DB 校验必须验证 `msg.talker == to_wxid`（防 display_name 串号）
|
||
|
||
### 8.7 状态机恢复
|
||
- **启动时全量清场**：`_full_cleanup_on_startup` 连续重置 3 次 + 截图校验
|
||
- **失败时重置**：`_reset_to_idle` 多策略清场（Esc×3 + 点击空白 + BackSpace×30 + Esc×2 + 校验）
|
||
- **正常路径只做轻清场**：Esc×1 + BackSpace×30（约 1s）
|
||
- 重置后必须 post_verify（匹配 main_view 模板）
|
||
|
||
### 8.8 错误分类与重试
|
||
- **可重试**：RATE_LIMITED / SEND_TIMEOUT / STATE_DIRTY / X11_TEMP_UNAVAILABLE
|
||
- **不可重试**：WECHAT_NOT_LOGGED_IN / WINDOW_NOT_FOUND / ELEMENT_NOT_FOUND / DB_VERIFY_FAILED / AMBIGUOUS_CONTACT / X11_UNAVAILABLE / BRIDGE_CIRCUITED
|
||
- UI 自动化最多重试 1 次（重试前必 `_reset_to_idle`）
|
||
- 指数退避 + 抖动：`base=1s, max=30s`
|
||
- `DB_VERIFY_FAILED` 不可重试（消息可能已发，重试即重复）
|
||
|
||
### 8.9 可观测性
|
||
- Prometheus `/metrics` 端点
|
||
- 关键指标：`woc_send_total{result}` / `woc_send_duration_seconds` / `woc_send_failed_by_state_total{state}` / `woc_image_match_confidence` / `woc_db_verify_duration_seconds` / `woc_send_queue_pending` / `woc_wechat_running` / `woc_circuit_state{name}`
|
||
- TraceID 贯穿单次请求所有日志行
|
||
- 调试截图带 trace_id 文件名
|
||
|
||
### 8.10 模板维护
|
||
- 深色/浅色模式两套模板（`light/` 和 `dark/`）
|
||
- 当前已提供浅色模式截图素材：`02-聊天界面.png`、`03-主界面.png`
|
||
- `01-搜索框.png` 含下拉覆盖层，**不可**作为模板，仅作反面参考
|
||
- 启动时检测主题（截主界面与参考图比对）
|
||
- 微信版本升级监控：`woc_image_match_confidence` 均值跌至 0.7 以下告警
|
||
- 多尺度匹配 `[1.0, 0.75, 1.25, 1.5]` 覆盖常见 DPI
|
||
- 采集模板时固定 DPI=96
|
||
- 模板裁剪坐标参考见 9.2 节
|
||
|
||
---
|
||
|
||
## 九、YAML Profile 规范
|
||
|
||
### 9.1 文件命名规则
|
||
|
||
```
|
||
profiles/
|
||
├── default.yaml # 兜底默认值
|
||
├── wechat_4.0_1920x1080.yaml # 精确匹配版本+分辨率
|
||
├── wechat_4.0_1280x720.yaml
|
||
├── wechat_4.0.yaml # 仅版本匹配
|
||
└── templates/
|
||
└── wechat_4.0/
|
||
├── light/ # 浅色模式
|
||
│ ├── search_box.png
|
||
│ ├── send_button.png
|
||
│ ├── input_box.png
|
||
│ ├── input_box_empty.png
|
||
│ └── main_view.png # 主界面模板（校验用）
|
||
└── dark/ # 深色模式
|
||
└── ...（同名）
|
||
```
|
||
|
||
### 9.2 截图素材参考
|
||
|
||
用户已提供 3 张微信真实截图，位于 `bridge/ui/profiles/templates/screenshot/`。阶段 2 模板采集可直接基于这些截图裁剪。
|
||
|
||
| 文件名 | 状态 | 用途 | 裁剪建议 |
|
||
|---|---|---|---|
|
||
| `01-搜索框.png` | ⚠️ 不可用（含下拉覆盖层） | 仅作参考，不可直接作为 `search_box.png` 模板 | 图中搜索框被点击，出现"搜索网络结果"下拉，模板必须从未激活状态截取 |
|
||
| `02-聊天界面.png` | ✅ 可用 | `send_button.png` / `input_box.png` / `input_box_empty.png` | 截取右下角绿色发送按钮、底部输入框、空输入框 |
|
||
| `03-主界面.png` | ✅ 可用 | `search_box.png` / `main_view.png` / `search_result_first.png` | 截取左栏顶部未激活搜索框、右侧主界面空白+微信 logo |
|
||
|
||
**主题判断**：当前为**浅色模式**（白色背景、绿色气泡），阶段 2 模板保存到 `templates/wechat_4.0/light/`。深色模式需等切换后重新采集。
|
||
|
||
**裁剪坐标参考（基于 1920x1080 截图）**：
|
||
|
||
| 模板 | 来源截图 | 建议裁剪区域（x, y, w, h） | 说明 |
|
||
|---|---|---|---|
|
||
| `search_box.png` | `03-主界面.png` | (40, 32, 230, 36) | 左栏顶部搜索框，不包含网络结果下拉 |
|
||
| `main_view.png` | `03-主界面.png` | (600, 300, 400, 300) | 右侧主区域空白+微信 logo |
|
||
| `search_result_first.png` | `03-主界面.png` | (40, 90, 230, 60) | 搜索框下方第一条会话结果 |
|
||
| `send_button.png` | `02-聊天界面.png` | (右下角 -80, -45, 70, 35) | 绿色激活态"发送"按钮 |
|
||
| `input_box.png` | `02-聊天界面.png` | (350, 1010, 500, 40) | 底部输入框 |
|
||
| `input_box_empty.png` | `02-聊天界面.png` | (350, 1010, 500, 40) | 空输入框（灰色提示文字状态） |
|
||
|
||
> **注意**：01-搜索框.png 是错误示例——包含"搜索网络结果"覆盖层。阶段 2 裁剪模板时必须使用 03-主界面.png 中的未激活搜索框。
|
||
|
||
### 9.3 YAML 字段规范
|
||
|
||
```yaml
|
||
<element_kind>:
|
||
by_image: "wechat_4.0/light/send_button.png"
|
||
by_geom:
|
||
relative_to: window
|
||
x_ratio: 0.0
|
||
y_ratio: 0.0
|
||
x_offset: 0
|
||
y_offset: 0
|
||
threshold: 0.80 # 图像匹配阈值
|
||
require_image: false # 高风险操作设 true
|
||
description: "发送按钮"
|
||
```
|
||
|
||
### 9.4 加载优先级
|
||
|
||
`LocatorRegistry.load(app_version, resolution)` 按以下顺序查找：
|
||
|
||
1. `wechat_{app_version}_{W}x{H}.yaml` — 精确匹配
|
||
2. `wechat_{app_version}.yaml` — 版本匹配
|
||
3. `default.yaml` — 默认兜底
|
||
|
||
---
|
||
|
||
## 十、迁移与兼容策略
|
||
|
||
### 10.1 不破坏现有功能
|
||
- 旧 `xdotool_driver.py` 保留作为兼容层
|
||
- 新代码通过 `capabilities.py` 调用
|
||
- send_queue 保留
|
||
- DB reader 保留
|
||
|
||
### 10.2 渐进式路由切换
|
||
|
||
| 路由 | 阶段 1 | 阶段 2 | 阶段 3 |
|
||
|---|---|---|---|
|
||
| `/api/send/text` | 旧实现 | 旧实现 | **新实现** |
|
||
| `/api/send/file` | 旧实现 | 旧实现 | 新实现 |
|
||
| `/api/moments/publish` | 旧实现 | 旧实现 | 旧实现（CDP 待阶段 4） |
|
||
| `/api/messages/revoke` | 旧实现 | **新实现** | 新实现 |
|
||
|
||
### 10.3 回滚方案
|
||
|
||
环境变量 `WOC_UI_BACKEND=legacy` 强制走旧实现：
|
||
|
||
```python
|
||
# bridge/routes/send.py
|
||
if config.ui_backend == "legacy":
|
||
result = await state.xdotool.send_text(...)
|
||
else:
|
||
result = await state.capabilities.send_text(...)
|
||
```
|
||
|
||
---
|
||
|
||
## 十一、预期收益
|
||
|
||
| 维度 | 当前 | 阶段 1 后 | 阶段 3 后 |
|
||
|---|---|---|---|
|
||
| 跨分辨率 | 1 个固定布局 | 同左 | 多 profile 自适应 + 图像匹配兜底 |
|
||
| 跨版本 | 微信更新即崩 | 同左 | 模板/profile 单独更新，代码不动 |
|
||
| 发送成功率 | ~70% | 同左 | >95%（DB 校验 + 图像校验） |
|
||
| **首条消息耗时** | **16s** | **~8s**（DB/截图/命令优化） | **3-5s**（自适应等待 + 并行） |
|
||
| **同联系人后续耗时** | **16s** | **~8s** | **1-2s**（会话缓存 + 队列自适应） |
|
||
| 失败可恢复 | 不可恢复，半残状态 | 启动清场 + 重置 | 状态机重置到 IDLE + 截图校验 |
|
||
| 重复发送风险 | 高（重试即重发） | 同左 | 低（5 分钟幂等 + client_request_id） |
|
||
| 子进程泄漏 | 有（取消时不 kill） | 无（上下文管理器） | 无 |
|
||
| 磁盘泄漏 | 有（调试截图堆积） | 无（生产关闭 + 自动清理） | 无 |
|
||
| 崩溃感知 | 无（被动触发） | 同左 | 10s watchdog 主动感知 |
|
||
| 可观测性 | 散点日志 | 同左 | Prometheus metric + TraceID |
|
||
| 错误分类 | 全部 SEND_FAILED | DB 校验区分 verified | 8 类错误码，区分可重试 |
|
||
| 熔断保护 | 无 | 同左 | DB + 图像 双熔断 |
|
||
|
||
---
|
||
|
||
## 十二、风险与应对
|
||
|
||
| 风险 | 概率 | 影响 | 应对 |
|
||
|---|---|---|---|
|
||
| OpenCV 模板匹配在深色模式下失效 | 中 | 定位失败 | 采集深色/浅色两套模板，启动时检测主题 |
|
||
| DB 校验延迟过高 | 低 | 发送后等 5 秒 | 降级到截图校验 |
|
||
| 微信版本升级改变 UI 布局 | 中 | 模板失效 | `woc_image_match_confidence` 均值监控 + 告警 |
|
||
| 状态机回滚不彻底 | 中 | 下一次发送失败 | 重置后 post_verify + 3 次重试 + 告警 |
|
||
| OpenCV 依赖增加镜像体积 | 低 | 镜像变大 ~50MB | 可接受 |
|
||
| CDP 端口开启后微信不稳定 | 中 | 微信崩溃 | 阶段 4 PoC 充分验证，失败则放弃 CDP |
|
||
| 幂等缓存 bridge 重启丢失 | 低 | 短窗口内重试重发 | 可从 DB 重建（远期） |
|
||
| watchdog 误判微信崩溃 | 低 | 误 pkill 微信 | 连续 2 次失败才触发 |
|
||
| 模板截图包含临时覆盖层导致匹配失败 | 中 | `search_box` 模板命中 0% | 模板必须从未激活/稳定态截取；`01-搜索框.png` 已标记为不可用 |
|
||
| 多 DPI/缩放比例下几何坐标偏移 | 中 | 图像未命中且几何不准 | 多尺度匹配 `[1.0, 0.75, 1.25, 1.5]` + 每分辨率独立 profile |
|
||
|
||
---
|
||
|
||
## 十三、验收标准
|
||
|
||
### 13.1 阶段验收
|
||
|
||
**阶段 1 验收**：
|
||
- [ ] `BackendProtocol` 定义完成，`XdotoolBackend` 实现通过所有现有测试
|
||
- [ ] YAML profile 加载机制工作，`default.yaml` 与现有硬编码常量一致
|
||
- [ ] `capabilities.send_text()` 行为与旧 `xdotool_driver.send_text()` 完全一致
|
||
- [ ] 生产环境 `_DEBUG_SCREENSHOTS=false`
|
||
- [ ] 无子进程泄漏（压力测试取消 100 次，无僵尸进程）
|
||
- [ ] bridge 启动后微信 UI 处于已知态（截图校验通过）
|
||
|
||
**阶段 2 验收**：
|
||
- [ ] 5 个 MVP 模板（搜索框/发送按钮/输入框/空输入框/主界面）采集完成
|
||
- 已有截图素材：`02-聊天界面.png`、`03-主界面.png`
|
||
- `search_box.png` 必须从 `03-主界面.png` 中未激活搜索框裁剪（不可用 `01-搜索框.png`）
|
||
- [ ] 1280x720 分辨率下发送文本成功率 > 90%
|
||
- [ ] 1920x1080 分辨率下图像匹配命中率 > 95%（基于已有截图验证）
|
||
- [ ] 图像匹配失败时回退到几何定位
|
||
- [ ] 撤回操作在图像未命中时拒绝执行
|
||
- [ ] `woc_image_match_confidence` metric 可查
|
||
|
||
**阶段 3 验收**：
|
||
- [ ] `SendTextFlow` 状态机实现完成，9 个状态全部覆盖
|
||
- [ ] 5 分钟内重复发送相同内容（同 client_request_id）跳过率 100%
|
||
- [ ] 不同 client_request_id 的相同内容可正常发送
|
||
- [ ] 发送失败时返回 `verified=False`，不返回 `SEND_FAILED`
|
||
- [ ] 发错人时返回 `DB_VERIFY_FAILED`（不可重试）
|
||
- [ ] 失败后状态机回滚到 IDLE，下一次发送正常
|
||
- [ ] Prometheus `/metrics` 端点可查
|
||
- [ ] 微信崩溃后 watchdog 10s 内感知
|
||
|
||
### 13.2 整体验收
|
||
|
||
- [ ] 单条文本消息端到端耗时 < 10 秒
|
||
- [ ] 发送成功率 > 95%（连续 100 次测试）
|
||
- [ ] 5 分钟内重复发送跳过率 100%
|
||
- [ ] 无子进程泄漏（压力测试）
|
||
- [ ] 无磁盘泄漏（7 天运行 /tmp/woc_debug < 100MB）
|
||
- [ ] 状态机日志清晰可读（状态、耗时、置信度、trace_id）
|
||
- [ ] 新增 UI 流程开发时间 < 2 小时
|
||
|
||
---
|
||
|
||
## 十四、附录
|
||
|
||
### 14.1 技术约束备忘
|
||
|
||
| 约束 | 来源 | 影响 |
|
||
|---|---|---|
|
||
| 微信主 UI 是 Qt 自绘 | [docker/Dockerfile:28](../docker/Dockerfile#L28) | CDP/AT-SPI 不可用 |
|
||
| WeChatAppEx 是 Chromium | [docker/Dockerfile:41](../docker/Dockerfile#L41) | CDP 理论可行（需 PoC） |
|
||
| 不响应 X11 修饰键组合 | 项目记忆 | 必须用 `xdotool type` + 鼠标点击 |
|
||
| 主进程不吃命令行参数 | [docker/autostart:23-25](../docker/autostart#L23) | CDP 开启需 LD_PRELOAD |
|
||
| send_queue 最小 3000ms 间隔 | [config.py:128](../bridge/woc_bridge/config.py#L128) | 单条消息下限 3 秒 |
|
||
| DB 密钥在主进程 [heap] 段 | 项目记忆 | key 提取只扫主进程堆 |
|
||
| WeChat 4.x 消息分片存储 | 项目记忆 | `Msg_<MD5(username)>` 表 |
|
||
| send_queue 已串行但无锁无幂等 | [send_queue.py:117](../bridge/woc_bridge/messaging/send_queue.py#L117) | 需在 L5 补幂等 |
|
||
| DB 校验已实现但错误处理不当 | [routes/send.py:265](../bridge/woc_bridge/routes/send.py#L265) | 需区分 verified vs success |
|
||
|
||
### 14.2 不采用的方案与原因
|
||
|
||
| 方案 | 不采用原因 |
|
||
|---|---|
|
||
| pyautogui | 与 xdotool 底层相同（X11 XTest），不解决核心问题 |
|
||
| AT-SPI / dogtail | Qt 自绘应用无 a11y 树，完全失效 |
|
||
| Frida native hook | 需逆向微信符号，工作量大，封号风险高 |
|
||
| SikuliX | JVM 依赖重，OpenCV 纯 Python 已足够 |
|
||
| transitions 库 | 状态数 < 10，自写更简单 |
|
||
| 逐级状态机回滚 | UI 操作不可逆，直接重置到 IDLE 更可靠 |
|
||
| Flow 内加 asyncio.Lock | 与 send_queue 双重串行，语义混乱 |
|
||
| 幂等键用 MD5 截断 8 位 | 短消息碰撞风险，用完整 SHA256 |
|
||
| 持久化幂等缓存 | 引入 SQLite/Redis 复杂度，收益低 |
|
||
|
||
### 14.3 参考项目
|
||
|
||
| 项目 | 方向 | 借鉴点 |
|
||
|---|---|---|
|
||
| [wechat-dump-rs](https://github.com/0xlane/wechat-dump-rs) | DB 解密 | 手机号定位 key 思路 |
|
||
| [wechat-decrypt](https://github.com/ylytdeng/wechat-decrypt) | DB 解析 | 4.0 表结构与消息内容解析 |
|
||
| [WeChatFerry](https://github.com/lich0821/WeChatFerry) | Hook 架构 | Windows only，仅参考架构设计 |
|
||
| [OpenCV 官方教程](https://docs.opencv.org/4.x/d4/dc6/tutorial_py_template_matching.html) | 图像识别 | 模板匹配最佳实践 |
|
||
| [Playwright CDP](https://playwright.dev/python/docs/cdp) | CDP 连接 | `connect_over_cdp` 用法 |
|
||
| [prometheus-client](https://github.com/prometheus/client_python) | 监控 | Python Prometheus 客户端 |
|
||
|
||
### 14.4 术语表
|
||
|
||
| 术语 | 含义 |
|
||
|---|---|
|
||
| Backend | 执行后端，封装 xdotool/OpenCV/CDP |
|
||
| Locator | 元素定位策略，图像/几何/CDP |
|
||
| Selector | 声明式元素选择器，YAML 配置 |
|
||
| ElementHandle | 元素句柄，包含坐标与置信度 |
|
||
| Action | 原子动作，组合 Backend + Locator |
|
||
| Flow | 业务流程，状态机编排多个 Action |
|
||
| Orchestrator | 流程编排器，管理幂等与重试 |
|
||
| Capability | 对外业务接口 |
|
||
| IdemCache | 幂等缓存，5 分钟去重 |
|
||
| CircuitBreaker | 熔断器，连续失败后熔断 |
|
||
| Watchdog | 崩溃感知后台任务 |
|
||
| ResourceReaper | 资源回收后台任务 |
|
||
| Profile | UI 元素配置文件 |
|
||
| TraceID | 贯穿单次请求的日志追踪 ID |
|
||
|
||
---
|
||
|
||
## 十五、接口调用速度优化（v3.0 新增）
|
||
|
||
### 15.1 速度瓶颈定位
|
||
|
||
通过逐行代码分析（见 1.2.3 节），当前 `send_text` 端到端时序拆解：
|
||
|
||
```
|
||
当前流程（典型 16s / 最坏 26s）：
|
||
├─ 会话定位 _open_session_by_name ~10s
|
||
│ ├─ find_wechat_window ~50ms
|
||
│ ├─ _activate_window_fast ~2s ← 已用自适应轮询（100ms 步进）
|
||
│ ├─ sleep 1.0s × 7 处 7.0s ← 【最大瓶颈】固定等待
|
||
│ ├─ _click_at × 2 ~200ms ← 两次 fork 可合并
|
||
│ ├─ _key × 4 ~200ms
|
||
│ ├─ _paste_via_xclip (name) ~200ms ← 方法名误导，实际是 xdotool type
|
||
│ └─ _debug_screenshot × 1 ~100ms ← 写磁盘 I/O
|
||
├─ 发送体 _send_body ~3s
|
||
│ ├─ _debug_screenshot × 4 ~400ms ← 写磁盘 I/O
|
||
│ ├─ _click_input_box ~100ms
|
||
│ ├─ _paste_via_xclip (content) ~200ms
|
||
│ ├─ sleep 1.0s × 2 处 2.0s ← 【瓶颈】
|
||
│ └─ _click_send_button ~100ms
|
||
├─ DB 校验 _verify_sent_to_talker 0-10s ← 【瓶颈】轮询 0.5s 间隔
|
||
└─ send_queue 延时 3.0s ← 任务后强制 sleep
|
||
```
|
||
|
||
**三大瓶颈**（占总耗时 80%+）：
|
||
1. **固定 sleep**：10 处 × 1.0s = 10s（会话定位 7s + 发送体 2s + 队列 3s 含此延时）
|
||
2. **DB 校验超时**：10s 超时 + 0.5s 轮询间隔（实际 DB 写入 < 500ms）
|
||
3. **无会话缓存**：每次重新搜索会话（连续发给同一人也重走 10s）
|
||
|
||
### 15.2 优化策略总览
|
||
|
||
| 策略 | 节省耗时 | 实施成本 | 阶段 |
|
||
|---|---|---|---|
|
||
| **A. 固定 sleep → 自适应轮询** | 5-7s | 中 | 阶段 3 |
|
||
| **B. 会话缓存（同联系人复用）** | 10s（后续） | 中 | 阶段 3 |
|
||
| **C. DB 校验调优** | 7-9s | 低 | 阶段 1 |
|
||
| **D. 调试截图移出关键路径** | 0.5s | 极低 | 阶段 1 |
|
||
| **E. 合并 xdotool 命令** | 0.5-1s | 低 | 阶段 1 |
|
||
| **F. 并行化 DB 查询与 UI 操作** | 1-2s | 低 | 阶段 3 |
|
||
| **G. 队列延时自适应** | 2s（同联系人） | 低 | 阶段 3 |
|
||
|
||
**预期效果**：
|
||
- 首条消息：16s → 3-5s（省 70%）
|
||
- 同联系人后续：16s → 1-2s（省 90%）
|
||
- 不同联系人切换：16s → 3-5s
|
||
|
||
### 15.3 策略 A：固定 sleep → 自适应轮询
|
||
|
||
**问题**：当前 10 处 `sleep 1.0s` 是"保守等待 UI 响应"，但 UI 实际响应通常 < 200ms。
|
||
|
||
**方案**：用条件轮询替代固定等待，条件满足即继续，超时兜底。
|
||
|
||
```python
|
||
# bridge/ui/flows/send_text.py
|
||
async def _wait_for_condition(
|
||
self, condition_fn, timeout: float = 3.0, interval: float = 0.15,
|
||
) -> bool:
|
||
"""轮询等待条件成立，满足即返回 True，超时返回 False。"""
|
||
deadline = time.monotonic() + timeout
|
||
while time.monotonic() < deadline:
|
||
if await condition_fn():
|
||
return True
|
||
await asyncio.sleep(interval)
|
||
return False
|
||
|
||
async def _click_search_box(self, ctx: FlowContext) -> FlowState:
|
||
await self.actions.click_element("search_box", ctx.win_geom)
|
||
# 旧：await asyncio.sleep(1.0)
|
||
# 新：轮询等待搜索框获得焦点（光标出现）
|
||
await self._wait_for_condition(
|
||
lambda: self._is_search_focused(ctx.win_geom),
|
||
timeout=2.0, interval=0.15,
|
||
)
|
||
return FlowState.SEARCH_BOX_CLICKED
|
||
|
||
async def _type_query(self, ctx: FlowContext) -> FlowState:
|
||
await self.actions.backend.key_press("BackSpace", repeat=30)
|
||
await asyncio.sleep(0.2) # BackSpace 无需长等
|
||
await self.actions.backend.type_text(ctx.display_name)
|
||
# 旧：await asyncio.sleep(1.0)
|
||
# 新：轮询等待搜索结果出现（图像匹配结果列表）
|
||
await self._wait_for_condition(
|
||
lambda: self.actions.find_element("search_result_list", ctx.win_geom),
|
||
timeout=3.0, interval=0.15,
|
||
)
|
||
return FlowState.QUERY_TYPED
|
||
```
|
||
|
||
**条件检测方式**：
|
||
- 搜索框聚焦：`xdotool getwindowfocus` + 图像匹配光标
|
||
- 搜索结果出现：图像匹配搜索结果列表模板
|
||
- 会话打开：图像匹配右侧聊天面板 / 输入框
|
||
- 输入完成：无需等待（xdotool type 同步返回）
|
||
- 发送完成：DB 校验（见策略 C）
|
||
|
||
**效果**：7s sleep → ~1-2s 自适应等待，节省 5-6s。
|
||
|
||
**容错**：条件未满足时不报错，用 timeout 兜底，记录到 metric。
|
||
|
||
### 15.4 策略 B：会话缓存（同联系人复用）
|
||
|
||
**问题**：连续发给同一联系人时，每次都重新搜索会话（10s），浪费 9.8s。
|
||
|
||
**方案**：维护"当前已打开会话"状态，匹配则跳过会话定位。
|
||
|
||
```python
|
||
# bridge/ui/orchestrator.py
|
||
class SessionCache:
|
||
"""当前已打开会话的缓存。
|
||
|
||
缓存 key = display_name，value = 打开时间戳。
|
||
TTL = 30s（30s 内无操作则认为微信可能切走了，缓存失效）。
|
||
"""
|
||
|
||
def __init__(self, ttl: float = 30.0):
|
||
self._ttl = ttl
|
||
self._current: Optional[tuple[str, float]] = None # (display_name, opened_at)
|
||
|
||
def get(self) -> Optional[str]:
|
||
"""返回当前已打开会话的 display_name，过期或无则 None。"""
|
||
if self._current is None:
|
||
return None
|
||
name, ts = self._current
|
||
if time.monotonic() - ts > self._ttl:
|
||
self._current = None
|
||
return None
|
||
return name
|
||
|
||
def set(self, display_name: str) -> None:
|
||
self._current = (display_name, time.monotonic())
|
||
|
||
def invalidate(self) -> None:
|
||
"""显式失效（如发送失败、状态机重置时）。"""
|
||
self._current = None
|
||
|
||
|
||
class FlowOrchestrator:
|
||
def __init__(self, ...):
|
||
self.session_cache = SessionCache(ttl=30.0)
|
||
|
||
async def send_text(self, to_wxid: str, content: str,
|
||
display_name: str = None, ...):
|
||
# 幂等检查...
|
||
|
||
async def _run():
|
||
flow = SendTextFlow(self.actions, self.db, self.session_cache)
|
||
ctx = FlowContext(...)
|
||
return await flow.run(ctx)
|
||
|
||
result = await self.send_queue.enqueue(_run)
|
||
# 失败时失效会话缓存
|
||
if not result.success:
|
||
self.session_cache.invalidate()
|
||
return result
|
||
|
||
|
||
# bridge/ui/flows/send_text.py
|
||
class SendTextFlow(Flow):
|
||
def __init__(self, actions, db, session_cache: SessionCache):
|
||
super().__init__(actions, db)
|
||
self.session_cache = session_cache
|
||
|
||
async def run(self, ctx: FlowContext) -> FlowResult:
|
||
t_start = time.perf_counter()
|
||
|
||
# 检查会话缓存
|
||
cached_session = self.session_cache.get()
|
||
session_cached = (cached_session == ctx.display_name)
|
||
|
||
if session_cached:
|
||
# 跳过会话定位，直接聚焦输入框
|
||
logger.info("[flow] 会话缓存命中，跳过定位")
|
||
state = FlowState.SESSION_OPENED
|
||
# 仅做轻量焦点校验
|
||
await self._verify_session_still_open(ctx)
|
||
else:
|
||
# 完整会话定位流程
|
||
state = await self._activate(ctx)
|
||
state = await self._click_search_box(ctx)
|
||
state = await self._type_query(ctx)
|
||
state = await self._open_session(ctx)
|
||
self.session_cache.set(ctx.display_name)
|
||
|
||
# 共同的发送流程
|
||
state = await self._focus_input(ctx)
|
||
state = await self._type_content(ctx)
|
||
state = await self._send(ctx)
|
||
state = await self._cleanup(ctx)
|
||
# ...
|
||
```
|
||
|
||
**缓存失效条件**：
|
||
- 发送失败（状态机重置）
|
||
- TTL 过期（30s 无操作）
|
||
- 显式 invalidate（如切换联系人、Esc 退会话）
|
||
|
||
**注意**：缓存命中后仍需轻量校验，确认会话还开着（图像匹配输入框），防止微信后台切走。
|
||
|
||
**效果**：同联系人后续消息从 16s → 3-4s（省 10s 会话定位 + 部分 sleep）。
|
||
|
||
### 15.5 策略 C：DB 校验调优
|
||
|
||
**问题**：当前 `_verify_sent_to_talker`（[routes/send.py:107](../bridge/woc_bridge/routes/send.py#L107)）：
|
||
- 超时 10s（实际 DB 写入 < 500ms）
|
||
- 轮询间隔 0.5s（太慢，第一次命中要等 0.5s）
|
||
- 失败后继续等到 10s（浪费时间）
|
||
|
||
**方案**：
|
||
|
||
```python
|
||
# bridge/ui/flows/send_text.py
|
||
async def _verify_sent(self, ctx: FlowContext) -> bool:
|
||
"""DB 校验调优：超时 3s + 轮询 0.2s + 早退出。"""
|
||
if not self.db or ctx.before_msg_id == 0:
|
||
return await self._verify_by_screenshot(ctx)
|
||
|
||
deadline = time.monotonic() + 3.0 # 从 10s 降到 3s
|
||
while time.monotonic() < deadline:
|
||
msgs = await self.db.get_messages(
|
||
ctx.to_wxid, limit=1, after_local_id=ctx.before_msg_id,
|
||
)
|
||
if msgs:
|
||
msg = msgs[0]
|
||
if (msg.talker == ctx.to_wxid
|
||
and msg.content == ctx.content
|
||
and msg.is_sender):
|
||
return True
|
||
# talker 不匹配 = 发错人，立即返回 False（不继续等）
|
||
logger.error("[verify] talker 不匹配: expected=%s actual=%s",
|
||
ctx.to_wxid, msg.talker)
|
||
return False
|
||
await asyncio.sleep(0.2) # 从 0.5s 降到 0.2s
|
||
return False
|
||
```
|
||
|
||
**调优依据**：
|
||
- 微信 DB 写入延迟实测 < 500ms（SQLCipher 同步写入）
|
||
- 轮询 0.2s → 典型命中只需 1 次轮询（0.2-0.4s）
|
||
- 超时 3s 覆盖 99% 场景（P99 < 1s）
|
||
- talker 不匹配时立即退出，不浪费时间
|
||
|
||
**效果**：DB 校验从 0-10s → 0.2-3s（典型 0.4s）。
|
||
|
||
### 15.6 策略 D：调试截图移出关键路径
|
||
|
||
**问题**：当前 `_DEBUG_SCREENSHOTS=True` 在关键路径上写 5 张 PNG ≈ 500ms（含磁盘 I/O 阻塞）。
|
||
|
||
**方案**：
|
||
|
||
```python
|
||
# bridge/ui/backends/xdotool.py
|
||
class XdotoolBackend:
|
||
def __init__(self, ...):
|
||
self._debug_shots_enabled = os.environ.get("WOC_UI_DEBUG_SHOTS", "false").lower() == "true"
|
||
self._debug_queue: asyncio.Queue = asyncio.Queue()
|
||
self._debug_task: Optional[asyncio.Task] = None
|
||
|
||
async def _debug_screenshot_async(self, step: str, trace_id: str = "") -> None:
|
||
"""异步截图：不阻塞关键路径，丢到后台队列写磁盘。"""
|
||
if not self._debug_shots_enabled:
|
||
return
|
||
# 只入队，不等待写盘
|
||
await self._debug_queue.put((step, trace_id, time.time()))
|
||
|
||
async def _debug_writer(self) -> None:
|
||
"""后台 worker：从队列取截图写磁盘。"""
|
||
while True:
|
||
step, trace_id, ts = await self._debug_queue.get()
|
||
try:
|
||
path = f"/tmp/woc_debug/{trace_id}_{step}_{int(ts*1000)}.png"
|
||
await self._run(["scrot", path])
|
||
except Exception as e:
|
||
logger.warning("[backend] 调试截图失败: %s", e)
|
||
```
|
||
|
||
**关键改进**：
|
||
1. 生产环境默认关闭（`WOC_UI_DEBUG_SHOTS=false`）
|
||
2. 开启时用后台队列异步写盘，不阻塞关键路径
|
||
3. 文件名带 trace_id，便于排障
|
||
4. 配合 ResourceReaper 自动清理
|
||
|
||
**效果**：500ms → 0ms（生产）/ < 5ms（调试，入队开销）。
|
||
|
||
### 15.7 策略 E：合并 xdotool 命令
|
||
|
||
**问题**：当前 `_click_at`（[xdotool_driver.py:399](../bridge/woc_bridge/ui/xdotool_driver.py#L399)）分两条命令：
|
||
```python
|
||
await self._run(["xdotool", "mousemove", "--sync", str(x), str(y)]) # fork 1
|
||
await self._run(["xdotool", "click", "1"]) # fork 2
|
||
```
|
||
每次 fork+exec 约 30-50ms，两次 = 60-100ms。
|
||
|
||
**方案**：合并为单条命令：
|
||
|
||
```python
|
||
# bridge/ui/backends/xdotool.py
|
||
async def click(self, x: int, y: int) -> None:
|
||
async with self._ui_lock:
|
||
# 合并 mousemove + click 为单条命令
|
||
await self._run([
|
||
"xdotool", "mousemove", "--sync", str(x), str(y),
|
||
"click", "1",
|
||
])
|
||
```
|
||
|
||
xdotool 支持链式命令，单条命令内顺序执行。
|
||
|
||
**效果**：每次点击节省 30-50ms，整流程 ~5 次点击 = 节省 150-250ms。
|
||
|
||
### 15.8 策略 F：并行化 DB 查询与 UI 操作
|
||
|
||
**问题**：发送前查 `before_msg_id`（[routes/send.py:90](../bridge/woc_bridge/routes/send.py#L90)）与 UI 激活窗口串行，可并行。
|
||
|
||
**方案**：
|
||
|
||
```python
|
||
# bridge/ui/flows/send_text.py
|
||
async def _activate_and_prepare(self, ctx: FlowContext) -> FlowState:
|
||
"""并行：激活窗口 + 查询发送前 DB 最新 msg_id。"""
|
||
# 两个独立任务并行
|
||
activate_task = asyncio.create_task(self._activate(ctx))
|
||
db_task = asyncio.create_task(self._fetch_before_msg_id(ctx))
|
||
|
||
await asyncio.gather(activate_task, db_task)
|
||
return FlowState.WINDOW_ACTIVATED
|
||
|
||
async def _fetch_before_msg_id(self, ctx: FlowContext) -> None:
|
||
"""查询发送前的 DB 最新 msg_id（并行执行，不阻塞 UI）。"""
|
||
if self.db:
|
||
try:
|
||
ctx.before_msg_id = await self.db.get_latest_msg_id(ctx.to_wxid)
|
||
except Exception:
|
||
ctx.before_msg_id = 0
|
||
```
|
||
|
||
**效果**：节省 DB 查询时间（~100-200ms），与窗口激活重叠。
|
||
|
||
### 15.9 策略 G：队列延时自适应
|
||
|
||
**问题**：当前 `send_delay_ms=3000`（[config.py:128](../bridge/woc_bridge/config.py#L128)）对所有情况一刀切。
|
||
|
||
**方案**：同联系人后续消息延时更短，不同联系人保持原延时。
|
||
|
||
```python
|
||
# bridge/ui/orchestrator.py
|
||
class FlowOrchestrator:
|
||
async def send_text(self, ...):
|
||
cached_session = self.session_cache.get()
|
||
session_cached = (cached_session == display_name)
|
||
|
||
async def _run():
|
||
flow = SendTextFlow(self.actions, self.db, self.session_cache)
|
||
ctx = FlowContext(...)
|
||
return await flow.run(ctx)
|
||
|
||
# 自适应延时
|
||
if session_cached:
|
||
delay = min(self.config.send_delay_ms, 1000) # 同联系人 1s
|
||
else:
|
||
delay = self.config.send_delay_ms # 不同联系人 3s
|
||
|
||
result = await self.send_queue.enqueue(_run, delay_ms=delay)
|
||
return result
|
||
|
||
|
||
# messaging/send_queue.py
|
||
class SendQueue:
|
||
async def enqueue(self, coro_factory: CoroFactory,
|
||
delay_ms: Optional[int] = None) -> Any:
|
||
"""入队，可选自定义延时（覆盖默认 send_delay_ms）。"""
|
||
...
|
||
|
||
async def _run(self):
|
||
while True:
|
||
coro_factory, future, custom_delay = await self._queue.get()
|
||
...
|
||
finally:
|
||
self._queue.task_done()
|
||
delay = custom_delay if custom_delay is not None else self.send_delay_ms
|
||
await asyncio.sleep(delay / 1000.0)
|
||
```
|
||
|
||
**理由**：
|
||
- 同联系人：会话已打开，微信 UI 不需要长缓冲，1s 足够
|
||
- 不同联系人：需要切换会话，UI 需要时间稳定，保持 3s
|
||
|
||
**效果**：同联系人后续消息队列延时 3s → 1s。
|
||
|
||
### 15.10 优化后预期时序
|
||
|
||
**首条消息（不同联系人）**：
|
||
```
|
||
├─ 激活窗口 + DB 查询（并行） ~2s
|
||
├─ 点击搜索框（自适应等待） ~0.3s
|
||
├─ 输入搜索词（自适应等待结果） ~0.5s
|
||
├─ 点击搜索结果（自适应等待会话打开） ~0.5s
|
||
├─ 聚焦输入框 ~0.3s
|
||
├─ 输入内容 + 点击发送 ~0.5s
|
||
├─ DB 校验（3s 超时，典型 0.4s） ~0.4s
|
||
├─ 清理（Esc） ~0.3s
|
||
└─ 队列延时 ~3s
|
||
总计：~4.8s（从 16s 降至 4.8s，省 70%）
|
||
```
|
||
|
||
**同联系人后续消息**：
|
||
```
|
||
├─ 会话缓存命中（跳过定位） ~0s
|
||
├─ 聚焦输入框 ~0.3s
|
||
├─ 输入内容 + 点击发送 ~0.5s
|
||
├─ DB 校验 ~0.4s
|
||
├─ 清理 ~0.3s
|
||
└─ 队列延时（自适应 1s） ~1s
|
||
总计：~2.5s（从 16s 降至 2.5s，省 84%）
|
||
```
|
||
|
||
### 15.11 实施阶段对照
|
||
|
||
| 策略 | 阶段 1 | 阶段 2 | 阶段 3 |
|
||
|---|---|---|---|
|
||
| A. 自适应轮询 | - | - | ✅ |
|
||
| B. 会话缓存 | - | - | ✅ |
|
||
| C. DB 校验调优 | ✅ | ✅ | ✅ |
|
||
| D. 调试截图异步 | ✅ | ✅ | ✅ |
|
||
| E. 合并 xdotool | ✅ | ✅ | ✅ |
|
||
| F. 并行 DB 查询 | - | - | ✅ |
|
||
| G. 队列延时自适应 | - | - | ✅ |
|
||
|
||
**阶段 1 即可落地 C/D/E**（低成本，无需新架构），立即节省 ~8s（DB 校验 7s + 截图 0.5s + 合并命令 0.2s）。
|
||
|
||
### 15.12 速度监控指标
|
||
|
||
```python
|
||
# bridge/ui/metrics.py
|
||
# 首条 vs 缓存命中耗时分布
|
||
send_duration_first = Histogram(
|
||
"woc_send_duration_first_seconds", "First send (no cache)",
|
||
buckets=[1, 2, 3, 5, 8, 12, 16, 25],
|
||
)
|
||
send_duration_cached = Histogram(
|
||
"woc_send_duration_cached_seconds", "Cached session send",
|
||
buckets=[0.5, 1, 1.5, 2, 3, 5],
|
||
)
|
||
# 会话缓存命中率
|
||
session_cache_hit = Counter(
|
||
"woc_session_cache_total", "Session cache hit/miss",
|
||
["result"], # hit / miss
|
||
)
|
||
# 自适应等待超时次数
|
||
adaptive_wait_timeout = Counter(
|
||
"woc_adaptive_wait_timeout_total", "Adaptive wait timeout",
|
||
["step"], # search_box / search_result / session_open
|
||
)
|
||
```
|
||
|
||
**告警阈值**：
|
||
- `woc_send_duration_first_seconds` P95 > 8s → 排查自适应等待是否失效
|
||
- `woc_session_cache_hit{result="miss"}` 占比 > 80% → 排查缓存 TTL
|
||
- `woc_adaptive_wait_timeout_total` 增长率 > 10/min → 模板可能失效
|
||
|
||
### 15.13 速度与可靠性的平衡
|
||
|
||
**核心原则**：速度优化不能牺牲可靠性。
|
||
|
||
| 场景 | 速度优先 | 可靠性优先 | 决策 |
|
||
|---|---|---|---|
|
||
| 会话缓存命中后是否跳过焦点校验 | 是（省 0.3s） | 否（防微信切走） | **否**，必须轻量校验 |
|
||
| DB 校验超时设为多短 | 1s | 3s | **3s**，覆盖 P99 |
|
||
| 自适应等待超时是否报错 | 否（容错继续） | 是（严格） | **否**，timeout 兜底 + 记录 metric |
|
||
| 队列延时同联系人设多短 | 500ms | 1s | **1s**，给微信 UI 刷新时间 |
|
||
| 合并 xdotool 命令是否影响错误定位 | 是（单条失败难定位） | 否（分步可定位） | **合并**，日志记录命令内容 |
|
||
|
||
**关键约束**：
|
||
- 自适应等待的 timeout 不小于 2s（防止 UI 偶发慢响应误判）
|
||
- 会话缓存 TTL 不超过 30s（防止微信自动切走后误用）
|
||
- DB 校验 talker 不匹配时立即退出（不缩短超时，但早退）
|
||
- 队列延时不低于 1s（同联系人）/ 3s（不同联系人）
|
||
|
||
---
|
||
|
||
## 十六、附录：实施检查清单
|
||
|
||
### 16.1 阶段 1 检查清单（P0 高可用 + 速度初步优化）
|
||
|
||
- [ ] `_CMD_TIMEOUT_SEC` 从 15s 降到 5s
|
||
- [ ] `_run_managed` 上下文管理器实现，取消时 kill+wait
|
||
- [ ] `_step` 的 `max(1.0, remaining)` 改为 `max(7.0, remaining)`
|
||
- [ ] 生产环境 `WOC_UI_DEBUG_SHOTS=false`
|
||
- [ ] 调试截图改为异步队列写盘
|
||
- [ ] `_click_at` 合并 mousemove + click 为单条命令
|
||
- [ ] DB 校验超时从 10s 降到 3s，轮询从 0.5s 降到 0.2s
|
||
- [ ] DB 校验 talker 不匹配时立即退出
|
||
- [ ] bridge 启动时执行 `_full_cleanup_on_startup`
|
||
- [ ] 现有 `/api/send/text` 接口行为不变
|
||
- [ ] 无子进程泄漏（压力测试）
|
||
|
||
### 16.2 阶段 3 检查清单（状态机 + 速度全面优化）
|
||
|
||
- [ ] `SendTextFlow` 状态机实现，9 个状态覆盖
|
||
- [ ] 固定 sleep 改为自适应轮询（10 处）
|
||
- [ ] 会话缓存 `SessionCache` 实现（TTL 30s）
|
||
- [ ] 队列延时自适应（同联系人 1s / 不同 3s）
|
||
- [ ] DB 查询与窗口激活并行
|
||
- [ ] 幂等缓存含 `client_request_id`
|
||
- [ ] 错误码分类（8 类）
|
||
- [ ] 熔断器（DB + 图像）
|
||
- [ ] Watchdog 微信/Xvnc 崩溃感知
|
||
- [ ] Prometheus metric 暴露
|
||
- [ ] TraceID 贯穿日志
|
||
- [ ] 首条消息 P95 < 5s
|
||
- [ ] 同联系人后续 P95 < 3s
|