# UIActionScheduler 统一调度方案

> 文档版本：v1.0
> 创建日期：2026-07-17
> 范围：`bridge/woc_bridge` 全链路
> 目标：将散落在 5 个子系统的 UI 操作收口到统一调度器，消除绕过队列的竞态风险，引入优先级与可观测性

---

## 一、背景与现状

### 1.1 当前架构

当前 UI 操作分散在 5 个子系统，串行化覆盖不完整：

| 子系统 | 入口 | 是否经 SendQueue | 互斥情况 |
|---|---|---|---|
| `FlowOrchestrator.send_text/send_file` | HTTP + BatchWorker | ✅ 入队 | SendQueue 串行 + `_ui_lock` 单命令互斥 |
| `routes/contacts.py` (set_remark/add_friend/accept) | HTTP | ✅ 入队 | 同上 |
| `routes/moments.py` (publish/share/like/comment/delete) | HTTP | ✅ 入队 | 同上 |
| `routes/send.py` legacy (revoke/forward) | HTTP | ✅ 入队 | 同上 |
| `FriendRequestWatcher._handle_request` | 后台轮询 3s | ✅ 入队 | 同上 |
| `routes/login.py` (logout/restart) | HTTP | ❌ 直接调 xdotool | 仅 `_ui_lock` 单命令互斥 |
| `routes/login.py` (qr_start/qr_wait) | HTTP | ❌ 直接调 xdotool | qr_capture **无锁** |
| `routes/screenshot.py` | HTTP | ❌ 直接调 qr_capture | **无锁** |
| `routes/diagnostic.py` (autofix) | HTTP | ❌ 内联 pkill | **无锁** |
| `LoginGuard._check_loop` | 后台轮询 5s | ❌ 直接调 xdotool | 仅 `_ui_lock` |
| `WeChatWatchdog._run` | 后台轮询 10s | ❌ 直接调 pgrep/kill | **无锁** |

### 1.2 已确认的问题

#### P0 竞态风险（已发生过实际故障）

| 问题 | 根因 | 后果 | 引用 |
|---|---|---|---|
| friend_watcher 与 send_text 竞态 | 早期未入队，现已修复入队 | erratic clicking、重复拨号 | 项目记忆记录 |
| logout 多步操作被 send_queue 任务穿插 | logout 不入队，仅靠 `_ui_lock` 单命令互斥 | 菜单状态错乱、登出失败 | [routes/login.py:201](../../bridge/woc_bridge/routes/login.py#L201) |
| restart kill 微信与并发 UI 操作冲突 | restart 不入队 | xdotool 对空窗口操作、TimeoutError 雪崩 | [routes/login.py:281](../../bridge/woc_bridge/routes/login.py#L281) |
| diagnostic autofix pkill 无锁 | 直接 `pkill -x wechat` | 与并发 UI 操作冲突高风险 | [routes/diagnostic.py:232-239](../../bridge/woc_bridge/routes/diagnostic.py#L232) |
| QrCapture 无锁无超时 | `proc.communicate()` 无 timeout | 与 send_text 截图竞争 X11、可能无限阻塞 | [ui/qr_capture.py:48-57](../../bridge/woc_bridge/ui/qr_capture.py#L48) |
| WeChatWatchdog autofix 无锁 | pgrep+kill 不持 `_ui_lock` | kill 微信时 UI 操作中途失败 | [ui/watchdog.py:99-191](../../bridge/woc_bridge/ui/watchdog.py#L99) |

#### P1 设计债务

| 问题 | 根因 | 后果 |
|---|---|---|
| 无优先级机制 | SendQueue 是纯 FIFO | 紧急操作（logout/restart）无法插队，100 个 send 排队时 logout 延迟分钟级 |
| 命名与实现不符 | 类名 `SendQueue`，实际是通用 UI 队列 | 误导维护者认为只管 send |
| 路由层前置 `detect_login_state` 不入队 | 多处路由在 enqueue 前直接调 xdotool | 与 send_queue 内任务竞争 `_ui_lock`，增加排队延迟 |
| 启动清场不入队 | `_full_cleanup_on_startup` 直接调 | 若 friend_watcher 已启动可能并发（实际启动顺序规避了此风险） |
| 无统一可观测性 | 各子系统独立打日志，无统一 metrics | UI 操作队列深度、等待时长、执行时长无法监控 |

#### P1.1 detect_login_state 散落调用分析

`detect_login_state` 是只读探测（截图 + 模板匹配），但散落在 14 处直接调用，每处都会与 send_queue 内任务竞争 L1 `_ui_lock`：

| 文件 | 调用位置 | 调用频率 | 与队列竞争影响 |
|---|---|---|---|
| `routes/send.py` | L307 / L413 / L587 / L690 / L774 / L852（6 处） | 每次 HTTP 请求 | 每次持锁 ~200-500ms（screenshot+模板匹配），100 并发 send 时累计 12-30s 额外延迟 |
| `routes/moments.py` | L151 / L255 / L346 / L447 / L545 / L677（6 处） | 每次 HTTP 请求 | 同上 |
| `routes/contacts.py` | L236 / L313 / L433（3 处） | 每次 HTTP 请求 | 同上 |
| `routes/login.py` | L117 / L190（2 处） | 每次 HTTP 请求 | 同上 |
| `routes/diagnostic.py` | L114（1 处） | 诊断触发 | 频率低，影响小 |
| `routes/status.py` | L51-56（内联判定，未直接调） | 每次 status 请求 | 已优化为内联 pgrep/find_window，**不持 _ui_lock** |
| `LoginGuard._check_loop` | 后台 5s 轮询 | 持续运行 | 每 5s 一次，频率低 |
| `friend_watcher._verify_with_retry` | 后台触发 | 偶发 | 频率低 |

**关键发现**：`routes/status.py` 已经通过内联 pgrep+find_window 避开了 `detect_login_state`，证明这种"只读探测不持 _ui_lock"的优化路径是可行且被项目采纳的。

**处理方案**（**本方案不强制收口，但记录优化路径**）：

1. **短期（本方案不实施）**：保持现状。`detect_login_state` 是单次截图+模板匹配，持锁时间可控（< 1s）。在 send_queue 任务执行期间（通常 1-5s），最多 1-2 次 detect_login_state 抢占 _ui_lock，影响有限。
2. **中期（独立优化项）**：参照 `routes/status.py` 的优化模式，将路由前置 `detect_login_state` 改为内联 pgrep + find_window 判定（不持 _ui_lock），仅在判定为 "logged_in" 后才入队执行真正的 UI 操作。
3. **长期（架构演进）**：LoginGuard 维护登录态缓存，路由层读缓存而非每次调 `detect_login_state`。

**为什么 UIActionScheduler 不收口 detect_login_state**：
- 入队会被 100 个 send 排队阻塞，导致登录态检测延迟分钟级，影响 friend_watcher 等依赖登录态的后台任务
- detect_login_state 是只读探测，不修改 UI 状态，与 send_queue 任务的"互斥"是性能问题而非正确性问题
- 收口 detect_login_state 会引入"队列内任务触发队列外只读探测"的循环依赖

**风险评估**：保持现状的代价是每个 send 请求多 ~300ms 延迟（detect_login_state 持锁 1 次），在 100 并发场景下累计 ~30s。可通过中期方案消除。

### 1.3 SendQueue 现状评估

SendQueue 实际上**已经是事实上的通用 UI 调度器**：
- 16 处 `enqueue` 调用点，覆盖 send(4)/contacts(3)/moments(6)/friend_watcher(1)/orchestrator(2)
- 接收任意 `CoroFactory`，不限定 send 语义
- 单 worker 串行 + 1 秒滑窗限流 + 队列满拒绝 + 等待超时

**可直接复用为基础**，但需扩展：
1. 增加 `priority` 参数（当前队列元素是 `tuple[CoroFactory, Future, Optional[int]]`，第三段是 `custom_delay_ms`，无 priority 槽位）
2. 重命名以反映通用语义（向后兼容保留别名）
3. 收口绕过队列的调用点

### 1.4 双层保护模型（L1 _ui_lock + L2 SendQueue）

当前架构存在两层互斥机制，理解其分工是设计 UIActionScheduler 的前提：

| 层级 | 互斥粒度 | 实现位置 | 持锁时长 | 保护语义 |
|---|---|---|---|---|
| **L1** `_ui_lock` | **单命令**（一次 click/type/screenshot） | `ui/backends/xdotool.py:50` `asyncio.Lock` | 单次 xdotool 子进程（~50ms-5s） | 防止两个 asyncio 协程同时调 xdotool 导致 X11 焦点错乱 |
| **L2** `SendQueue` | **多命令 Flow**（整个 send_text/logout 流程） | `messaging/send_queue.py` worker 串行 | 整个 Flow（~1-30s） | 防止多步操作之间被其他操作步骤穿插 |

**关键区别**：

```
send_text Flow（多步操作，L2 保护）：
  activate → click_search_box → type_query → open_session →
  focus_input → type_text → click_send → verify
  ↑ 每一步内部都 acquire/release L1 _ui_lock（单命令互斥）
  ↑ 整个 Flow 由 L2 SendQueue 串行执行（多步不被穿插）

logout Flow（多步操作，当前仅 L1 保护）：
  activate → click_main_menu → key_down × N → enter → click_confirm
  ↑ 每一步内部 acquire/release L1 _ui_lock
  ↑ 整个 Flow 不在 SendQueue 中 → send_text 的步骤可以穿插进来！
```

**核心问题**：L1 只保护单次命令，无法防止多步 Flow 被穿插。例如 logout 点击主菜单后释放 _ui_lock，send_text 立即获得 _ui_lock 执行 click_search_box，导致 logout 的下一步 key_down 落在错误的焦点上。

**UIActionScheduler 的职责**：提供 L2 层统一保护，所有多步 UI 操作必须入队，避免步骤穿插。L1 保持不变作为底层单命令互斥的第二道防线（防止绕过队列的极端情况，如 LoginGuard/detect_login_state）。

### 1.5 UI 操作调用点全景图

**修改前**（当前状态，散落 22 个调用点，仅 16 个入队）：

```
┌─ HTTP 路由层 ────────────────────────────────────────────────────────────┐
│                                                                          │
│  routes/send.py                                                          │
│    ├─ send_text (L337)         ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ send_file (L703)         ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ revoke_message (L787)    ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ forward_message (L881)   ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ detect_login_state × 6   ── direct ──→ xdotool    [⚠️ 仅 L1]     │
│    ├─ post_verify_revoke       ── direct ──→ DB only    [✅ 无 UI]      │
│    ├─ capture_forward_baseline ── direct ──→ DB only    [✅ 无 UI]      │
│    └─ post_verify_forward      ── direct ──→ DB only    [✅ 无 UI]      │
│                                                                          │
│  routes/contacts.py                                                      │
│    ├─ set_remark (L249)        ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ add_friend (L321)        ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ accept_friend (L452)     ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ detect_login_state × 3   ── direct ──→ xdotool    [⚠️ 仅 L1]     │
│    └─ post_verify_set_remark   ── direct ──→ DB only    [✅ 无 UI]      │
│       post_verify_add_friend                                              │
│                                                                          │
│  routes/moments.py                                                       │
│    ├─ publish (L167)           ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ share (L271)             ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ like (L379)              ── enqueue ──→ SendQueue  [✅ 入队]      │
│    │   └─ _like_and_verify     (含 post_verify_moment_like 含截图)      │
│    ├─ comment (L480)           ── enqueue ──→ SendQueue  [✅ 入队]      │
│    │   └─ _comment_and_verify  (含 post_verify_moment_comment 含截图)   │
│    ├─ delete (L583)            ── enqueue ──→ SendQueue  [✅ 入队]      │
│    ├─ forward_moment (L692)    ── enqueue ──→ SendQueue  [✅ 入队]      │
│    └─ detect_login_state × 6   ── direct ──→ xdotool    [⚠️ 仅 L1]     │
│                                                                          │
│  routes/login.py                                                         │
│    ├─ qr_start (L58-59)        ── direct ──→ xdotool+qr  [❌ P0 无锁]   │
│    ├─ qr_wait (L117)           ── direct ──→ xdotool    [⚠️ 仅 L1]     │
│    ├─ logout (L201)            ── direct ──→ xdotool    [❌ P0 仅 L1]   │
│    └─ wechat_restart (L281)    ── direct ──→ xdotool    [❌ P0 仅 L1]   │
│                                                                          │
│  routes/screenshot.py                                                    │
│    └─ screenshot (L42)         ── direct ──→ qr_capture [❌ P0 无锁]   │
│                                                                          │
│  routes/diagnostic.py                                                    │
│    ├─ autofix_wechat_running   ── direct ──→ pkill      [❌ P0 无锁]   │
│    └─ detect_login_state (L114)── direct ──→ xdotool    [⚠️ 仅 L1]     │
│                                                                          │
│  routes/status.py                                                        │
│    └─ 内联 pgrep+find_window  (不持 _ui_lock，已优化)    [✅ 无 UI]      │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

┌─ 后台任务层 ────────────────────────────────────────────────────────────┐
│                                                                          │
│  FlowOrchestrator (send_text/send_file)                                  │
│    ├─ enqueue (L231, L364)     ── enqueue ──→ SendQueue  [✅ 入队]      │
│    └─ SessionCache LRU                                                   │
│                                                                          │
│  FriendRequestWatcher._handle_request                                    │
│    └─ enqueue (L506)           ── enqueue ──→ SendQueue  [✅ 入队]      │
│                                                                          │
│  LoginGuard._check_loop                                                  │
│    └─ detect_login_state       ── direct ──→ xdotool    [⚠️ 仅 L1]     │
│                                                                          │
│  WeChatWatchdog._run                                                     │
│    ├─ pgrep/xdpyinfo           ── direct ──→ system     [✅ 只读]       │
│    └─ _autofix_wechat (kill)   ── direct ──→ kill       [❌ P0 无锁]   │
│                                                                          │
│  QrCapture                                                               │
│    └─ _run (proc.communicate) ── direct ──→ scrot       [❌ P0 无超时] │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

**修改后**（目标状态，所有 P0 收口，仅保留只读探测不入队）：

```
┌─ HTTP 路由层 ── 全部经 UIActionScheduler.execute(action, priority) ────┐
│                                                                          │
│  routes/send.py                                                          │
│    ├─ send_text/file/revoke/forward ── execute(NORMAL) ──→ Scheduler   │
│    ├─ detect_login_state × 6         ── direct (中期优化为内联 pgrep)   │
│    └─ post_verify_* / capture_baseline ── direct (DB only, 保留)        │
│                                                                          │
│  routes/contacts.py                                                      │
│    ├─ set_remark/add_friend/accept ── execute(NORMAL/HIGH) → Scheduler │
│    └─ detect_login_state × 3         ── direct (中期优化)               │
│                                                                          │
│  routes/moments.py                                                       │
│    ├─ publish/share/delete          ── execute(NORMAL) ──→ Scheduler   │
│    ├─ like/comment                  ── execute(LOW)     ──→ Scheduler   │
│    └─ detect_login_state × 6         ── direct (中期优化)               │
│                                                                          │
│  routes/login.py                                                         │
│    ├─ qr_start (capture_qr_code)   ── execute(HIGH)    ──→ Scheduler   │
│    ├─ logout                       ── execute(HIGH)    ──→ Scheduler   │
│    ├─ wechat_restart               ── execute(CRITICAL)──→ Scheduler   │
│    │                  └─ mark_wechat_dead(8.0) before execute           │
│    └─ qr_wait (detect_login_state) ── direct (只读，保留)               │
│                                                                          │
│  routes/screenshot.py                                                    │
│    └─ screenshot                   ── execute(LOW)     ──→ Scheduler   │
│                                                                          │
│  routes/diagnostic.py                                                    │
│    └─ autofix_wechat_running       ── execute(CRITICAL)──→ Scheduler   │
│                       └─ mark_wechat_dead(15.0) before execute          │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

┌─ 后台任务层 ────────────────────────────────────────────────────────────┐
│                                                                          │
│  FlowOrchestrator.send_text/send_file                                    │
│    └─ enqueue (向后兼容)         ── execute(NORMAL) ──→ Scheduler      │
│                                                                          │
│  FriendRequestWatcher._handle_request                                    │
│    └─ enqueue (向后兼容)         ── execute(HIGH)    ──→ Scheduler     │
│                                                                          │
│  LoginGuard._check_loop                                                  │
│    └─ detect_login_state         ── direct (只读，保留)                 │
│                                                                          │
│  WeChatWatchdog._autofix_wechat                                          │
│    ├─ scheduler.drain(5.0)       ── 等待队列清空                         │
│    ├─ scheduler.mark_wechat_dead(15.0) ── 标记 fast-fail 窗口           │
│    └─ pgrep + kill -TERM         ── 系统级操作（不入队）                 │
│                                                                          │
│  QrCapture._run                                                          │
│    └─ asyncio.wait_for(proc.communicate, 5.0) ── 超时保护               │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

### 1.6 HTTP 端点 → 优先级映射表

| HTTP 端点 | 当前状态 | 目标优先级 | delay_ms 策略 | wait_timeout_ms | 备注 |
|---|---|---|---|---|---|
| `POST /api/send/text` | ✅ enqueue | NORMAL | 同联系人 1000 / 不同 3000 | 15000 | 现有逻辑不变 |
| `POST /api/send/file` | ✅ enqueue | NORMAL | 默认 3000 | 15000 | 现有逻辑不变 |
| `POST /api/messages/revoke` | ✅ enqueue | NORMAL | 默认 3000 | 15000 | 现有逻辑不变 |
| `POST /api/messages/forward` | ✅ enqueue | NORMAL | 默认 3000 | 15000 | 现有逻辑不变 |
| `POST /api/friends/remark` | ✅ enqueue | NORMAL | 默认 3000 | 15000 | 现有逻辑不变 |
| `POST /api/friends/add` | ✅ enqueue | NORMAL | 默认 3000 | 15000 | 现有逻辑不变 |
| `POST /api/friends/accept` | ✅ enqueue | HIGH | 默认 3000 | 30000 | 时效性高 |
| `POST /api/moments/publish` | ✅ enqueue | NORMAL | 默认 3000 | 30000 | 现有逻辑不变 |
| `POST /api/moments/share` | ✅ enqueue | NORMAL | 默认 3000 | 30000 | 现有逻辑不变 |
| `POST /api/moments/delete` | ✅ enqueue | NORMAL | 默认 3000 | 15000 | 现有逻辑不变 |
| `POST /api/moments/forward` | ✅ enqueue | NORMAL | 默认 3000 | 30000 | 现有逻辑不变 |
| `POST /api/moments/like` | ✅ enqueue | LOW | 默认 3000 | 15000 | 可延迟 |
| `POST /api/moments/comment` | ✅ enqueue | LOW | 默认 3000 | 15000 | 可延迟 |
| `POST /api/screenshot` | ❌ direct | LOW | 默认 3000 | 10000 | 阶段 2 收口 |
| `POST /api/login/qr/start` | ❌ direct | HIGH | 默认 3000 | 15000 | 阶段 2 收口 |
| `POST /api/login/logout` | ❌ direct | HIGH | 默认 3000 | 30000 | 阶段 2 收口 |
| `POST /api/wechat/restart` | ❌ direct | CRITICAL | 0（自动） | 60000 | 阶段 2 收口 + fast-fail |
| `POST /api/diagnostic/autofix/wechat_running` | ❌ direct | CRITICAL | 0（自动） | 30000 | 阶段 2 收口 + fast-fail |
| `GET /api/login/qr/wait` | direct（轮询） | 不入队 | - | - | 只读探测 |
| `GET /api/status` | 内联 pgrep | 不入队 | - | - | 已优化 |
| `GET /api/diagnostic/run/*` | direct（只读） | 不入队 | - | - | 只读探测 |

---

## 二、设计方案

### 2.1 核心思路

**不推翻 SendQueue 重写，而是扩展 + 收口**：

1. **扩展 SendQueue** 为 `UIActionScheduler`，增加优先级参数
2. **收口绕过队列的 6 个调用点**，统一入队
3. **保留 `_ui_lock`** 作为底层单命令互斥（不取消，作为第二道防线）
4. **新增 metrics** 暴露队列深度、等待时长、执行时长

### 2.2 命名策略

采用**渐进式重命名**，避免一次性破坏全部调用点：

```python
# messaging/ui_action_scheduler.py（新文件，继承 SendQueue）
class UIActionScheduler(SendQueue):
    """UI 操作统一调度器。
    
    在 SendQueue 基础上增加：
    - priority 参数（CRITICAL/HIGH/NORMAL/LOW）
    - 优先级队列（asyncio.PriorityQueue 替代 asyncio.Queue）
    - metrics 暴露（队列深度、等待时长、执行时长）
    """
    async def execute(
        self,
        action: CoroFactory,
        priority: Priority = Priority.NORMAL,
        delay_ms: Optional[int] = None,
        wait_timeout_ms: Optional[int] = None,
        trace_id: str = "",
    ) -> Any:
        """提交 UI 操作，按优先级调度，串行执行。"""
        ...

# config.py
_state.send_queue: SendQueue | UIActionScheduler  # 渐进式，先保持字段名
```

**向后兼容**：
- 保留 `SendQueue.enqueue` 方法签名不变（priority 默认 NORMAL）
- 16 个现有 `enqueue` 调用点无需修改
- 新调用点用 `execute` 方法，语义更清晰

### 2.3 优先级策略

```python
class Priority(enum.IntEnum):
    """UI 操作优先级（数字越小优先级越高）。"""
    CRITICAL = 0   # 系统级紧急：wechat_restart、diagnostic_autofix
    HIGH = 1       # 用户感知延迟：logout、friend_accept、login_qr_capture
    NORMAL = 2     # 常规业务：send_text、send_file、set_remark、add_friend
    LOW = 3        # 可延迟：screenshot、moments_like、moments_comment
```

**优先级队列实现**：
- 使用 `asyncio.PriorityQueue`，元素为 `(priority, seq, coro_factory, future, delay_ms)`
- `seq` 是单调递增序列号，保证同优先级 FIFO（避免 coro_factory 不可比较导致的错误）
- worker 出队时按 `(priority, seq)` 排序

**优先级反转保护**：
- 低优先级操作持锁时，高优先级操作必须等待（无法抢占，xdotool 子进程不可中断）
- 缓解：限制单次操作超时（已有 `_Cmd_TIMEOUT_SEC=5.0` + Flow 30s 超时），避免低优先级操作长时间持锁
- 不实现优先级继承（xdotool 子进程无法感知调用方优先级）

#### 2.3.1 delay_ms 与优先级的交互策略

**当前 delay_ms 决策逻辑**（在 `orchestrator.py:212`）：
- 同联系人发送：`delay_ms=1000`（短延时，提升吞吐）
- 不同联系人发送：`delay_ms=None` → 用 `send_delay_ms=3000`（默认延时，避免风控）
- 路由层 `enqueue` 不传 `delay_ms` → 用默认 `send_delay_ms=3000`

**问题**：引入优先级后，CRITICAL/HIGH 操作的延时是否应区别处理？

**分析**：
- delay_ms 是任务**执行后**的等待时间，影响**下一个任务**的开始时机
- 例如：CRITICAL 的 restart 执行后，若 delay_ms=3000，下一个 NORMAL 任务要等 3s
- restart 本身的优先级已经让它排到队首，所以 delay_ms 不影响 restart 自身延迟

**策略**：

| 优先级 | delay_ms 策略 | 理由 |
|---|---|---|
| CRITICAL | `delay_ms=0`（不延时） | restart/autofix 后应立即让后续任务执行，避免无谓等待 |
| HIGH | `delay_ms=None`（用默认） | logout/accept_friend 后需要给微信 UI 恢复时间，保持默认延时 |
| NORMAL | 保持现有逻辑（同联系人 1000 / 不同 3000） | send 风控保护，不变 |
| LOW | `delay_ms=None`（用默认） | screenshot 后不强制延时，但也不加速，避免连续截图 |

**实现**：在 `scheduler.execute` 内根据 priority 自动覆盖 delay_ms：

```python
async def execute(
    self,
    action: CoroFactory,
    priority: Priority = Priority.NORMAL,
    delay_ms: Optional[int] = None,
    ...
) -> Any:
    # CRITICAL 任务自动应用 delay_ms=0（除非调用方显式指定）
    if priority == Priority.CRITICAL and delay_ms is None:
        delay_ms = 0
    return await self._enqueue_with_priority(
        action, priority, delay_ms, wait_timeout_ms, trace_id
    )
```

**注意**：调用方显式指定 `delay_ms` 时优先尊重调用方意图（如批量发送要求固定间隔）。

**对现有 enqueue 的影响**：无。现有 16 个 `enqueue` 调用点都走 `priority=NORMAL`，delay_ms 决策逻辑不变。

### 2.4 关键决策：watchdog 是否入队

**不入队，但加协同机制**：

WeChatWatchdog 的 `pgrep -x wechat` / `xdpyinfo` / `kill -TERM` 是**系统级操作**，不是 UI 操作：
- `pgrep`/`xdpyinfo`：只读探测，不修改 UI 状态，无需互斥
- `kill -TERM`：会杀死微信进程，导致所有进行中的 UI 操作失败

**方案**：
- watchdog 的 `pgrep`/`xdpyinfo` 保持现状（不入队，不加锁）
- watchdog 的 `_autofix_wechat` 在 kill 前检查 `scheduler.pending_count()`：
  - 若有 pending UI 操作，先 `await scheduler.drain(timeout=5.0)` 等待队列清空
  - 超时未清空则强制 kill（记 warning）
- kill 后广播 `wechat_killed` 事件，所有进行中的 Flow 捕获 `WINDOW_NOT_FOUND` 后自然失败

### 2.5 关键决策：QrCapture 如何收口

QrCapture 有两类操作：
1. `capture_qr_code`：启动扫码登录流程，**多步 UI 操作**（activate + screenshot + crop）
2. `capture_full_screenshot`：单次截图

**方案**：
- `capture_qr_code` 入队（priority=HIGH），与 send_text 串行
- `capture_full_screenshot` 入队（priority=LOW）
- QrCapture 内部增加 `_CMD_TIMEOUT_SEC=5.0` 包裹 `proc.communicate()`，消除无超时风险

### 2.6 关键决策：LoginGuard 是否入队

**不入队**，原因：
- `detect_login_state` 是只读探测（截图 + 模板匹配），不修改 UI 状态
- 5 秒轮询 + `_ui_lock` 单命令互斥已足够
- 若入队，会被 100 个 send 排队阻塞，登录态检测延迟可达分钟级，影响 friend_watcher 等依赖登录态的任务

**但需加保护**：
- `detect_login_state` 内部已有 `_ui_lock` 持锁（经 `_run`），保持现状
- 增加监控：若 `_ui_lock` 等待时长 > 2s，记 warning（说明 UI 操作积压）

---

## 三、详细设计

### 3.1 UIActionScheduler 类

```python
# bridge/woc_bridge/messaging/ui_action_scheduler.py

"""UI 操作统一调度器。

所有 xdotool/scrot 子进程调用经此调度器串行执行，避免并发 UI 操作冲突。
在 SendQueue 基础上增加优先级调度与可观测性。
"""

from __future__ import annotations

import asyncio
import enum
import logging
import time
from typing import Any, Awaitable, Callable, Optional

from woc_bridge.messaging.send_queue import SendQueue, CoroFactory
from woc_bridge.models import BridgeError

logger = logging.getLogger("woc-bridge")


class Priority(enum.IntEnum):
    """UI 操作优先级（数字越小优先级越高）。"""
    CRITICAL = 0   # 系统级紧急：wechat_restart、diagnostic_autofix
    HIGH = 1       # 用户感知延迟：logout、friend_accept、login_qr_capture
    NORMAL = 2     # 常规业务：send_text、send_file、set_remark、add_friend
    LOW = 3        # 可延迟：screenshot、moments_like、moments_comment


class UIActionScheduler(SendQueue):
    """UI 操作统一调度器。

    扩展 SendQueue：
    - execute() 方法支持 priority 参数
    - 内部用 asyncio.PriorityQueue 替代 asyncio.Queue（覆盖父类 __init__ 创建的 Queue）
    - 同优先级 FIFO（通过 seq 序列号保证，避免比较到不可比较的 coro_factory）
    - metrics 暴露（pending_count by priority、wait_duration、exec_duration）

    向后兼容：
    - enqueue() 方法保留，priority 默认 NORMAL
    - 现有 16 个 enqueue 调用点无需修改

    ⚠️ 必须覆盖父类 _run 方法：父类 _run 解包 3 元组 (coro_factory, future, delay_ms)，
       子类用 5 元组 (priority, seq, coro_factory, future, delay_ms)。
       若不覆盖会导致解包失败。
    """

    def __init__(
        self,
        send_delay_ms: int = 3000,
        max_calls_per_sec: int = 10,
        max_queue_size: int = 100,
    ) -> None:
        super().__init__(send_delay_ms, max_calls_per_sec, max_queue_size)
        # 覆盖父类 __init__ 创建的 asyncio.Queue 为 PriorityQueue
        # 父类的旧 Queue 对象会被 GC 回收（无其他引用）
        self._queue: asyncio.PriorityQueue[
            tuple[int, int, CoroFactory, asyncio.Future, Optional[int]]
        ] = asyncio.PriorityQueue(maxsize=max_queue_size)
        self._seq = 0  # 单调递增序列号，保证同优先级 FIFO

        # fast-fail 机制：mark_wechat_dead 标记的时间戳
        # 在此时间之前，所有非 CRITICAL 任务直接抛 WECHAT_NOT_READY
        # 供 watchdog kill / wechat_restart 调用，避免失败风暴
        self._wechat_dead_until: float = 0.0

        # metrics（简单计数器，供 /api/status 或 Prometheus 暴露）
        # asyncio 单线程事件循环，worker 与 HTTP handler 同线程，无需加锁
        self._metrics: dict[str, Any] = {
            "executed_total": 0,
            "executed_by_priority": {p.name: 0 for p in Priority},
            "wait_duration_ms_sum": 0.0,
            "exec_duration_ms_sum": 0.0,
            "timeout_total": 0,
            "rate_limited_total": 0,
            "fast_fail_total": 0,  # 被 mark_wechat_dead 拦截的任务数
        }

    def mark_wechat_dead(self, duration_sec: float = 10.0) -> None:
        """标记微信已死，期间所有非 CRITICAL 任务直接 fast-fail。

        供 watchdog kill / wechat_restart / diagnostic autofix 调用：
        - kill 前调 mark_wechat_dead(15.0)，覆盖 autostart 拉起窗口
        - restart 开始时调 mark_wechat_dead(8.0)，覆盖新进程启动窗口

        CRITICAL 任务（如 restart 本身）不受影响，确保 restart 能正常执行。

        Args:
            duration_sec: fast-fail 窗口时长（秒）
        """
        self._wechat_dead_until = time.monotonic() + duration_sec
        logger.warning(
            "[scheduler] mark_wechat_dead %.1fs, %d pending tasks will fast-fail",
            duration_sec, self._queue.qsize(),
        )

    async def execute(
        self,
        action: CoroFactory,
        priority: Priority = Priority.NORMAL,
        delay_ms: Optional[int] = None,
        wait_timeout_ms: Optional[int] = None,
        trace_id: str = "",
    ) -> Any:
        """提交 UI 操作，按优先级调度，串行执行。

        Args:
            action: 返回 coroutine 的工厂函数
            priority: 优先级（CRITICAL/HIGH/NORMAL/LOW）
            delay_ms: 自定义本次延时毫秒；None 时：
                      - CRITICAL 自动设为 0（执行后不延时）
                      - 其他优先级用默认 send_delay_ms
            wait_timeout_ms: 队列等待超时；None 无限等待
            trace_id: 追踪 ID（用于日志关联）

        Returns:
            coroutine 的实际执行结果

        Raises:
            BridgeError(RATE_LIMITED): 队列满
            BridgeError(TIMEOUT): 等待超时
        """
        # CRITICAL 任务自动应用 delay_ms=0（除非调用方显式指定）
        # 参见 2.3.1 节 delay_ms 与优先级交互策略
        if priority == Priority.CRITICAL and delay_ms is None:
            delay_ms = 0
        return await self._enqueue_with_priority(
            action, priority, delay_ms, wait_timeout_ms, trace_id
        )

    async def _enqueue_with_priority(
        self,
        coro_factory: CoroFactory,
        priority: Priority,
        delay_ms: Optional[int],
        wait_timeout_ms: Optional[int],
        trace_id: str,
    ) -> Any:
        """优先级入队（覆盖 SendQueue.enqueue 的内部实现）。

        与父类 enqueue 的差异：
        - 用 put_nowait 替代 await put（满队时立即抛错，语义更清晰）
        - 队列元素从 3 元组扩展为 5 元组（priority, seq, coro_factory, future, delay_ms）
        - 增加入队日志（与父类保持一致的可观测性）
        """
        loop = asyncio.get_running_loop()
        future: asyncio.Future = loop.create_future()
        self._seq += 1
        item = (int(priority), self._seq, coro_factory, future, delay_ms)

        # 入队（带队列满检查，与父类行为一致）
        try:
            self._queue.put_nowait(item)
        except asyncio.QueueFull:
            self._metrics["rate_limited_total"] += 1
            logger.warning(
                "[scheduler] 队列已满 (size=%d/%d)，拒绝入队 priority=%s",
                self._queue.maxsize, self._queue.maxsize, priority.name,
            )
            raise BridgeError(
                code="RATE_LIMITED",
                message=f"UI 调度器队列已满（{self._queue.maxsize}），请稍后重试",
                details={"retry_after": 3},
            )

        pending = self._queue.qsize()
        logger.info(
            "[scheduler] 入队 priority=%s pending=%d trace_id=%s",
            priority.name, pending, trace_id or "(none)",
        )

        # 等待结果（与父类逻辑一致，保留竞争窗口处理）
        wait_start = time.monotonic()
        if wait_timeout_ms is not None and wait_timeout_ms > 0:
            try:
                result = await asyncio.wait_for(
                    future, timeout=wait_timeout_ms / 1000.0
                )
            except asyncio.TimeoutError:
                # 竞争窗口：worker 可能刚好在此时完成并 set_result
                if future.done() and not future.cancelled():
                    logger.info(
                        "[scheduler] 等待超时但任务刚好完成，取结果 (pending=%d)",
                        pending,
                    )
                    return future.result()
                future.cancel()
                self._metrics["timeout_total"] += 1
                wait_sec = wait_timeout_ms / 1000.0
                logger.warning(
                    "[scheduler] 等待超时 (pending=%d, wait_timeout=%.1fs, priority=%s)",
                    pending, wait_sec, priority.name,
                )
                raise BridgeError(
                    code="TIMEOUT",
                    message=f"UI 调度器等待超时（{pending} 个待处理，已等 {wait_sec:.1f}s）",
                    details={"retry_after": max(1, int(self.send_delay_ms / 1000))},
                )
        else:
            result = await future

        # 记录等待时长
        wait_ms = (time.monotonic() - wait_start) * 1000
        self._metrics["wait_duration_ms_sum"] += wait_ms

        return result

    async def enqueue(
        self,
        coro_factory: CoroFactory,
        delay_ms: Optional[int] = None,
        wait_timeout_ms: Optional[int] = None,
    ) -> Any:
        """向后兼容的入队方法（priority 默认 NORMAL）。

        现有 16 个 enqueue 调用点无需修改，行为与父类一致。
        """
        return await self._enqueue_with_priority(
            coro_factory, Priority.NORMAL, delay_ms, wait_timeout_ms, ""
        )

    async def _run(self) -> None:
        """worker 主循环。

        ⚠️ 必须覆盖父类 _run：父类解包 3 元组，子类用 5 元组。

        与父类 _run 的差异：
        - 解包 5 元组 (priority, seq, coro_factory, future, custom_delay_ms)
        - 增加 metrics 记录（executed_total / executed_by_priority / exec_duration）
        - 保留限流检查（_check_rate_limit 继承父类，不覆盖）
        - 保留延时逻辑（delay_ms 优先于 send_delay_ms）
        - task_done 调用与父类一致：cancelled 分支和 finally 分支互斥
        """
        while True:
            try:
                priority, seq, coro_factory, future, custom_delay_ms = (
                    await self._queue.get()
                )
            except asyncio.CancelledError:
                raise

            # 调用方已超时取消：跳过执行与延时（与父类一致）
            if future.cancelled():
                self._queue.task_done()
                logger.info(
                    "[scheduler] 出队任务已取消，跳过 (pending=%d, priority=%s)",
                    self._queue.qsize(),
                    Priority(priority).name if 0 <= priority <= 3 else "?",
                )
                continue

            # fast-fail 检查：微信已死期间，非 CRITICAL 任务直接失败
            # 参见 6.4 节 失败风暴问题与 fast-fail 机制
            if (
                self._wechat_dead_until > time.monotonic()
                and priority > Priority.CRITICAL  # CRITICAL 任务（=0）不受影响
            ):
                logger.info(
                    "[scheduler] fast-fail (wechat dead, %.1fs remaining, priority=%s)",
                    self._wechat_dead_until - time.monotonic(),
                    Priority(priority).name if 0 <= priority <= 3 else "?",
                )
                if not future.done():
                    future.set_exception(BridgeError(
                        code="WECHAT_NOT_READY",
                        message="微信进程未就绪（重启中），请稍后重试",
                        details={"retry_after": 5},
                    ))
                self._metrics["fast_fail_total"] += 1
                self._queue.task_done()
                continue  # 不延时，立即处理下一个

            logger.info(
                "[scheduler] 出队，开始处理 (pending=%d, priority=%s)",
                self._queue.qsize(),
                Priority(priority).name if 0 <= priority <= 3 else "?",
            )
            executed = False
            t_exec = time.perf_counter()
            try:
                # 继承父类的限流检查
                self._check_rate_limit()
                self._recent_call_times.append(time.monotonic())
                executed = True
                logger.info("[scheduler] 开始执行任务 (priority=%s)", Priority(priority).name)
                result = await coro_factory()
                logger.info(
                    "[scheduler] 任务执行完成 (%.0fms, priority=%s)",
                    (time.perf_counter() - t_exec) * 1000,
                    Priority(priority).name,
                )
                if not future.done():
                    future.set_result(result)
            except asyncio.CancelledError:
                if not future.done():
                    future.cancel()
                raise
            except Exception as e:
                logger.warning(
                    "[scheduler] 任务执行抛异常 %s: %s (%.0fms, priority=%s)",
                    type(e).__name__, e,
                    (time.perf_counter() - t_exec) * 1000,
                    Priority(priority).name,
                )
                if not future.done():
                    future.set_exception(e)
            finally:
                self._queue.task_done()
                if executed:
                    # 更新 metrics
                    exec_ms = (time.perf_counter() - t_exec) * 1000
                    self._metrics["executed_total"] += 1
                    self._metrics["exec_duration_ms_sum"] += exec_ms
                    try:
                        p = Priority(priority)
                        self._metrics["executed_by_priority"][p.name] += 1
                    except ValueError:
                        pass

                    delay = (
                        custom_delay_ms
                        if custom_delay_ms is not None
                        else self.send_delay_ms
                    )
                    logger.info(
                        "[scheduler] 延时 %dms 后处理下一个 (priority=%s)",
                        delay, Priority(priority).name,
                    )
                    await asyncio.sleep(delay / 1000.0)

    def get_metrics(self) -> dict:
        """返回调度器指标（供 /api/status 或 Prometheus 暴露）。

        asyncio 单线程事件循环，与 worker 同线程，无需加锁。
        """
        return {
            **self._metrics,
            "pending_count": self._queue.qsize(),
        }

    async def drain(self, timeout: float = 5.0) -> bool:
        """等待队列清空（供 watchdog kill 微信前调用）。

        通过 _queue.join() 等待所有已入队任务被 task_done。
        worker 在 task_done 后可能仍在 sleep(delay)，但队列已空，
        sleep 结束后阻塞在 get() 上，不会执行新任务。

        边界条件：
        - worker 已停止时 join 会永远等待（无人调 task_done），靠 timeout 兜底
        - drain 返回 True 后、kill 前若有新任务入队，worker 可能开始执行
          （概率低，kill 后执行失败被正常捕获）

        Args:
            timeout: 最大等待秒数

        Returns:
            True 表示队列已清空，False 表示超时未清空
        """
        try:
            await asyncio.wait_for(self._queue.join(), timeout=timeout)
            return True
        except asyncio.TimeoutError:
            logger.warning(
                "[scheduler] drain timeout %.1fs, %d tasks pending",
                timeout, self._queue.qsize(),
            )
            return False
```

### 3.2 优先级分配

| 调用点 | 优先级 | 理由 |
|---|---|---|
| `routes/login.py` wechat_restart | CRITICAL | 系统级紧急，需尽快执行 |
| `routes/diagnostic.py` autofix_wechat_running | CRITICAL | 同上 |
| `routes/login.py` logout | HIGH | 用户主动操作，感知延迟 |
| `routes/login.py` qr_start (capture_qr_code) | HIGH | 登录流程关键步骤 |
| `routes/contacts.py` accept_friend_request | HIGH | 好友申请有时效性 |
| `friend_watcher._handle_request` | HIGH | 同上 |
| `routes/send.py` send_text (flow + legacy) | NORMAL | 常规业务 |
| `routes/send.py` send_file (flow + legacy) | NORMAL | 同上 |
| `routes/send.py` revoke / forward | NORMAL | 同上 |
| `routes/contacts.py` set_remark / add_friend | NORMAL | 同上 |
| `routes/moments.py` publish / share / delete | NORMAL | 同上 |
| `routes/moments.py` like / comment | LOW | 可延迟，不阻塞主流程 |
| `routes/screenshot.py` capture_full_screenshot | LOW | 可延迟 |
| `routes/login.py` qr_wait (detect_login_state 轮询) | **不入队** | 只读探测，保持现状 |
| `LoginGuard._check_loop` | **不入队** | 只读探测，保持现状 |
| `WeChatWatchdog._run` (pgrep/xdpyinfo) | **不入队** | 系统级探测，保持现状 |
| `WeChatWatchdog._autofix_wechat` (kill) | **不入队但协同** | kill 前调 scheduler.drain() |

### 3.3 收口方案（6 个 P0 调用点）

#### 3.3.1 routes/login.py - logout

**关键**：logout 路由在执行 logout 前会先调 `detect_login_state`（只读探测，不入队）。仅 `xdotool.logout()` 入队。

```python
# 修改前（routes/login.py:201）
if state_before == LoginState.LOGGED_IN.value:
    await xdotool.logout()  # 直接调，不入队

# 修改后
if state_before == LoginState.LOGGED_IN.value:
    scheduler = _require_send_queue()
    await scheduler.execute(
        lambda: xdotool.logout(),
        priority=Priority.HIGH,
        wait_timeout_ms=30000,  # logout 多步操作，给 30s
        trace_id="logout",
    )
```

**说明**：`detect_login_state` 保持不入队（只读探测，与 LoginGuard 一致），仅 `xdotool.logout()` 入队。

#### 3.3.2 routes/login.py - wechat_restart

```python
# 修改后（routes/login.py:281）
scheduler = _require_send_queue()
new_pid = await scheduler.execute(
    lambda: xdotool.restart_wechat(timeout_sec=timeout_sec),
    priority=Priority.CRITICAL,
    wait_timeout_ms=60000,  # restart 可能慢，给 60s
    trace_id="wechat_restart",
)
```

#### 3.3.3 routes/login.py - qr_start

```python
# 修改后（routes/login.py:58-59）
scheduler = _require_send_queue()

async def _qr_capture_flow():
    await xdotool._activate_window_fast()
    return await qr_capture.capture_qr_code()

qr_data_url = await scheduler.execute(
    _qr_capture_flow,
    priority=Priority.HIGH,
    wait_timeout_ms=15000,
    trace_id="qr_start",
)
```

#### 3.3.4 routes/screenshot.py

```python
# 修改后（routes/screenshot.py:42）
scheduler = _require_send_queue()
png_bytes = await scheduler.execute(
    lambda: qr_capture.capture_full_screenshot(),
    priority=Priority.LOW,
    wait_timeout_ms=10000,
    trace_id="screenshot",
)
```

#### 3.3.5 routes/diagnostic.py - autofix_wechat_running

```python
# 修改后（routes/diagnostic.py:230-249）
scheduler = _require_send_queue()

async def _autofix_flow():
    # pkill + check_pid + start_wechat 组合
    proc = await asyncio.create_subprocess_exec(
        "pkill", "-x", "wechat",
        stdout=asyncio.subprocess.DEVNULL,
        stderr=asyncio.subprocess.DEVNULL,
    )
    await proc.wait()
    await asyncio.sleep(2)  # 等 autostart 拉起
    new_pid = await xdotool.check_wechat_pid()
    if new_pid is None:
        new_pid = await xdotool.start_wechat(timeout_sec=10)
    return new_pid

new_pid = await scheduler.execute(
    _autofix_flow,
    priority=Priority.CRITICAL,
    wait_timeout_ms=30000,
    trace_id="autofix_wechat_running",
)
```

#### 3.3.6 QrCapture 超时修复

```python
# ui/qr_capture.py 修改（L48-57）
_CMD_TIMEOUT_SEC = 5.0  # 新增常量

async def _run(self, args: list[str]) -> tuple[int, bytes, bytes]:
    """执行一条命令并返回 (returncode, stdout, stderr)。"""
    proc = await asyncio.create_subprocess_exec(
        *args,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
        env=self._env(),
    )
    try:
        stdout, stderr = await asyncio.wait_for(
            proc.communicate(), timeout=_CMD_TIMEOUT_SEC
        )
        return proc.returncode, stdout, stderr
    except asyncio.TimeoutError:
        proc.kill()
        await proc.wait()
        raise
```

#### 3.3.7 WeChatWatchdog 协同

```python
# ui/watchdog.py 修改

class WeChatWatchdog:
    def __init__(
        self,
        backend: BackendProtocol,
        interval: float = 10.0,
        fail_threshold: int = 2,
        scheduler=None,  # 新增可选参数，向后兼容
    ) -> None:
        self.backend = backend
        self.interval = interval
        self.fail_threshold = fail_threshold
        self._scheduler = scheduler  # UIActionScheduler 实例（用于 drain）
        self._fail_count = 0
        self._task: Optional[asyncio.Task] = None
        self._stopped = False

    async def _autofix_wechat(self) -> None:
        logger.warning("[watchdog] autofix: killing wechat for restart")

        # kill 前等待 UI 操作队列清空（避免 kill 正在执行的 UI 操作）
        if self._scheduler is not None:
            drained = await self._scheduler.drain(timeout=5.0)
            if not drained:
                logger.warning(
                    "[watchdog] drain timeout, force kill with %d UI ops pending",
                    self._scheduler.pending_count(),
                )

        # 原有 kill 逻辑（pgrep + kill -TERM）保持不变
        try:
            proc = await asyncio.create_subprocess_exec(
                "pgrep", "-x", "wechat",
                stdout=asyncio.subprocess.PIPE,
                stderr=asyncio.subprocess.PIPE,
            )
            # ... 原有逻辑
```

**app.py 注入**：
```python
# app.py:499 修改
_state.watchdog = WeChatWatchdog(
    backend=_state.xdotool_backend,
    interval=10.0,
    scheduler=_state.send_queue,  # 新增：注入调度器
)
```

### 3.4 注入与生命周期

```python
# app.py _init_state 修改（替换 L383-L387）
from woc_bridge.messaging.ui_action_scheduler import UIActionScheduler, Priority

_state.send_queue = UIActionScheduler(  # 替换原 SendQueue
    send_delay_ms=cfg.send_delay_ms,
    max_calls_per_sec=cfg.max_calls_per_sec,
    max_queue_size=cfg.max_queue_size,
)
# _state.send_queue 类型注解保持 SendQueue（多态，UIActionScheduler 是子类）
# 现有 _require_send_queue() 返回 SendQueue 类型，调用方无需修改
# 调用方可用 hasattr(scheduler, 'execute') 判断是否支持优先级

# watchdog 注入 scheduler（app.py:499 修改）
_state.watchdog = WeChatWatchdog(
    backend=_state.xdotool_backend,
    interval=10.0,
    scheduler=_state.send_queue,  # 新增：注入调度器用于 drain
)
```

**生命周期不变**：
- `send_queue.start()` / `send_queue.stop()` 继承父类，lifespan 中保持原顺序
- `watchdog.start()` / `watchdog.stop()` 保持原顺序
- shutdown 时 `verify_bus.clear()` 在 `send_queue.stop()` 之前（已有逻辑）

### 3.5 Metrics 暴露

#### 3.5.1 StatusResponse 模型扩展

```python
# bridge/woc_bridge/models/status.py 修改
class StatusResponse(BaseModel):
    # ... 现有字段保持不变 ...
    send_queue_pending: int = Field(default=0, description="发送队列积压任务数")

    # 新增字段（Optional，向后兼容）
    ui_scheduler: Optional[dict] = Field(
        default=None,
        description="UI 调度器指标（仅 UIActionScheduler 实例才有）",
    )
```

#### 3.5.2 routes/status.py 暴露 metrics

```python
# routes/status.py 修改（L96 附近）
send_queue = _state.send_queue
send_queue_pending = send_queue.pending_count() if send_queue else 0
ui_scheduler_metrics = None
if send_queue is not None and hasattr(send_queue, 'get_metrics'):
    ui_scheduler_metrics = send_queue.get_metrics()

return StatusResponse(
    # ... 现有字段 ...
    send_queue_pending=send_queue_pending,
    ui_scheduler=ui_scheduler_metrics,
    # ...
)
```

返回示例：
```json
{
  "send_queue_pending": 0,
  "ui_scheduler": {
    "executed_total": 1234,
    "executed_by_priority": {
      "CRITICAL": 2,
      "HIGH": 15,
      "NORMAL": 1200,
      "LOW": 17
    },
    "wait_duration_ms_sum": 45678.9,
    "exec_duration_ms_sum": 234567.8,
    "timeout_total": 3,
    "rate_limited_total": 1,
    "pending_count": 0
  }
}
```

#### 3.5.3 激活已存在的 Prometheus metrics

**发现问题**：`ui/metrics.py:58` 已定义 `woc_send_queue_pending` Gauge，但**从未在任何地方 set 它的值**（已存在的 bug）。

```python
# ui/metrics.py 已有定义（无需修改）
send_queue_pending = Gauge(
    "woc_send_queue_pending",
    "Send queue pending count",
)

# 新增：在 routes/status.py 或 app.py 中激活
# 方案 A：在 status 接口中 set（每次查询时更新）
from woc_bridge.ui.metrics import send_queue_pending as send_queue_pending_gauge
if send_queue is not None:
    send_queue_pending_gauge.set(send_queue.pending_count())

# 方案 B：在 UIActionScheduler._run 中 set（每次出队时更新）
# 更实时但会增加 metrics 写入频率
```

**推荐方案 A**：在 status 接口中 set，与现有 `send_queue_pending` 字段同步更新，避免高频写入 Prometheus。

#### 3.5.4 新增 Prometheus metrics（可选，阶段 3）

```python
# ui/metrics.py 新增
from prometheus_client import Counter, Gauge, Histogram

ui_action_executed = Counter(
    "woc_ui_action_executed_total",
    "UI actions executed total",
    ["priority"],  # CRITICAL / HIGH / NORMAL / LOW
)

ui_action_wait_duration = Histogram(
    "woc_ui_action_wait_duration_seconds",
    "UI action wait duration (queue wait time)",
    buckets=(0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0),
)

ui_action_exec_duration = Histogram(
    "woc_ui_action_exec_duration_seconds",
    "UI action execution duration",
    ["priority"],
    buckets=(0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0),
)

ui_action_timeout = Counter(
    "woc_ui_action_timeout_total",
    "UI action wait timeout count",
)

ui_action_rate_limited = Counter(
    "woc_ui_action_rate_limited_total",
    "UI action rate limited (queue full) count",
)
```

在 `UIActionScheduler._run` 和 `_enqueue_with_priority` 中埋点。

---

## 四、迁移路径

### 阶段 1：基础设施（无破坏性）

**目标**：引入 UIActionScheduler，向后兼容现有调用

**改动**：
1. 新增 `messaging/ui_action_scheduler.py`（Priority + UIActionScheduler 类）
2. `app.py` 将 `SendQueue(...)` 替换为 `UIActionScheduler(...)`
3. `watchdog.py` 增加 `scheduler` 参数（可选，向后兼容）
4. `routes/status.py` 暴露 metrics

**验证**：
- py_compile 通过
- 现有 16 个 `enqueue` 调用点无需修改，行为不变
- `/api/status` 返回 `ui_scheduler` 字段

### 阶段 2：收口 P0 调用点

**目标**：消除 6 个绕过队列的竞态风险 + QrCapture 超时修复

**改动**：
1. `routes/login.py`：logout / restart / qr_start 改用 `scheduler.execute`
   - logout 仅 `xdotool.logout()` 入队，`detect_login_state` 保持不入队
2. `routes/screenshot.py`：改用 `scheduler.execute(priority=LOW)`
3. `routes/diagnostic.py`：autofix 改用 `scheduler.execute(priority=CRITICAL)`
4. `ui/qr_capture.py`：增加 `_CMD_TIMEOUT_SEC=5.0` 包裹 `proc.communicate()`
5. `ui/watchdog.py`：构造函数新增 `scheduler` 参数；`_autofix_wechat` 增加 `scheduler.drain()` 调用
6. `app.py`：`WeChatWatchdog(...)` 注入 `scheduler=_state.send_queue`

**验证**：
- py_compile 通过
- 并发调用 `POST /api/login/logout` + `POST /api/send/text` 不再竞态（logout 入队等待）
- `POST /api/screenshot` 与 send_text 串行执行
- watchdog autofix 前等待 UI 队列清空（`drain` 返回 True 后再 kill）
- QrCapture scrot 卡死时 5s 超时（不再无限阻塞）

### 阶段 3：可观测性增强（可选）

**目标**：提供 Prometheus metrics 和详细日志

**改动**：
1. `models/status.py`：`StatusResponse` 新增 `ui_scheduler: Optional[dict]` 字段
2. `routes/status.py`：暴露 `ui_scheduler` metrics + 激活已存在的 `woc_send_queue_pending` Gauge
3. `ui/metrics.py`：新增 `woc_ui_action_*` 系列 metrics（Counter/Histogram）
4. `UIActionScheduler._run` / `_enqueue_with_priority`：埋点写入 Prometheus metrics
5. 日志增加 `priority` 和 `trace_id` 字段（已在阶段 1 代码中包含）

**验证**：
- `GET /api/status` 返回 `ui_scheduler` 字段
- `/metrics` 端点返回 `woc_ui_action_executed_total` 等指标
- 日志可按 `priority=CRITICAL` 过滤
- 已存在的 `woc_send_queue_pending` Gauge 不再为 0（bug 修复）

---

## 五、验收标准

### AC-01：UIActionScheduler 向后兼容

**Given** 现有 16 个 `enqueue` 调用点未修改
**When** `app.py` 将 `SendQueue(...)` 替换为 `UIActionScheduler(...)`
**Then** 所有现有功能行为不变，py_compile 通过，单元测试通过

### AC-02：优先级调度生效

**Given** 队列中有 10 个 NORMAL 优先级的 send_text 任务
**When** 提交一个 CRITICAL 优先级的 wechat_restart
**Then** wechat_restart 优先于剩余 NORMAL 任务执行（可能在当前 NORMAL 任务执行完后立即执行）

### AC-03：logout 与 send_text 不再竞态

**Given** 一个 send_text 正在 send_queue 中执行
**When** 并发调用 `POST /api/login/logout`
**Then** logout 入队等待，send_text 执行完后 logout 才开始执行

### AC-04：QrCapture 有超时保护

**Given** scrot 子进程卡死
**When** `QrCapture._run` 执行
**Then** 5 秒后超时，`proc.kill()` + `await proc.wait()`，抛出 TimeoutError

### AC-05：watchdog autofix 协同

**Given** send_queue 中有 5 个 pending 任务
**When** watchdog 触发 `_autofix_wechat`
**Then** 先 `scheduler.drain(timeout=5.0)` 等待队列清空，超时则强制 kill 并记 warning

### AC-06：metrics 暴露

**Given** 调度器执行了若干操作
**When** 调用 `GET /api/status`
**Then** 返回 `ui_scheduler` 字段，包含 `executed_total` / `executed_by_priority` / `pending_count` 等指标

### 5.1 关键场景时序图

#### 5.1.1 修改前：logout 与 send_text 并发竞态

```
时刻 T0: send_text 正在执行（队列 worker 持有 coro_factory）
         ┌─────────────────────────────────────────────────────┐
Worker:  │ send_text Flow:                                    │
         │   activate → click_search → type_query → ...       │
         │   ↑ 每步持 L1 _ui_lock，步骤间释放                  │
         └─────────────────────────────────────────────────────┘

时刻 T1: HTTP 请求 POST /api/login/logout 到达
         ↓ logout 路由直接调 xdotool.logout()（不入队）
         ↓ logout 尝试 acquire _ui_lock → 等待 send_text 释放

时刻 T2: send_text 执行 click_search_box 完成释放 _ui_lock
         ↓ logout 抢到 _ui_lock，执行 activate
         ↓ logout 释放 _ui_lock
         ↓ send_text 抢到 _ui_lock，执行 type_query
         ↓ ❌ 焦点已被 logout 改变，type_query 输入到错误位置！

时刻 T3: logout 再次抢 _ui_lock 执行 click_main_menu
         ↓ ❌ send_text 可能仍在执行，菜单状态不可预测

结果：send_text 发错会话，logout 失败，UI 状态混乱
```

#### 5.1.2 修改后：logout 与 send_text 串行执行

```
时刻 T0: send_text 正在执行（worker 持有）
         ┌─────────────────────────────────────────────────────┐
Worker:  │ send_text Flow (NORMAL priority)                   │
         │   activate → click_search → type_query → ...       │
         └─────────────────────────────────────────────────────┘

时刻 T1: HTTP 请求 POST /api/login/logout 到达
         ↓ logout 路由调 scheduler.execute(logout, HIGH, 30s)
         ↓ 入队 (HIGH, seq=N)，pending=1
         ↓ worker 仍在执行 send_text，logout 等待 future

时刻 T2: send_text 完成，worker 出队
         ↓ PriorityQueue 出队 (HIGH, N)（优先于其他 NORMAL 任务）
         ↓ 执行 xdotool.logout() 完整流程（多步操作不被穿插）
         ↓ logout 完成，返回 success

结果：send_text 与 logout 串行，UI 状态正确
```

#### 5.1.3 watchdog kill 与 drain 协同

```
时刻 T0: send_queue 中有 5 个 pending send_text
         worker 正在执行第 1 个 send_text

时刻 T1: watchdog 检测到 wechat 不响应（fail_count >= 2）
         ↓ watchdog 调 _autofix_wechat
         ↓ scheduler.drain(timeout=5.0)
         ↓ 等待 _queue.join()，worker 继续执行当前任务

时刻 T2: worker 完成当前 send_text（task_done）
         ↓ _queue.join() 检查未完成任务数
         ↓ 仍有 4 个 pending（task_done 计数未归零）
         ↓ worker 出队下一个 send_text 并执行...
         ↓ ⚠️ 若每个 send_text 耗时 > 1.25s，5s 内无法清空

时刻 T3a (5s 内清空):
         ↓ drain 返回 True
         ↓ scheduler.mark_wechat_dead(15.0)  ← 启动 fast-fail 窗口
         ↓ pgrep + kill -TERM wechat
         ↓ 后续 15s 内新入队任务直接 fast-fail（WECHAT_NOT_READY）

时刻 T3b (5s 超时未清空):
         ↓ drain 返回 False，记 warning
         ↓ scheduler.mark_wechat_dead(15.0)
         ↓ pgrep + kill -TERM wechat
         ↓ ❌ 仍有 N 个 pending 任务，kill 后每个都会失败一次

时刻 T4: autostart 拉起新 wechat 进程（~5-10s）
         ↓ mark_wechat_dead 窗口未到期，新任务继续 fast-fail
         ↓ 窗口到期后，新任务正常执行（wechat 已就绪）

结果：drain 减少失败任务数，mark_wechat_dead 避免失败风暴放大
```

#### 5.1.4 优先级插队场景

```
时刻 T0: 队列状态：[send1(NORMAL,seq=1), send2(NORMAL,seq=2), ..., send10(NORMAL,seq=10)]
         worker 正在执行 send1

时刻 T1: HTTP 请求 POST /api/wechat/restart 到达
         ↓ scheduler.execute(restart, CRITICAL, 0ms, 60s)
         ↓ 入队 (CRITICAL=0, seq=11)
         ↓ PriorityQueue 重排：[(0,11), (2,2), (2,3), ..., (2,10)]
         ↓ pending=10（restart 排第 1）

时刻 T2: send1 完成，worker 出队
         ↓ 出队 (0, 11) → restart 任务
         ↓ scheduler.mark_wechat_dead(8.0)  ← 标记 fast-fail 窗口
         ↓ 执行 restart_wechat (60s 超时)

时刻 T3: restart 完成（~5s）
         ↓ 后续 8s 内 (mark_wechat_dead 窗口)：
         ↓   send2-send10 出队 → 检查 _wechat_dead_until → fast-fail
         ↓   客户端收到 WECHAT_NOT_READY + retry_after=5
         ↓ 8s 后窗口到期，新任务正常执行

结果：restart 在 1 个 send 完成后立即执行（不等 send2-send10），
      后续 send 通过 fast-fail 快速失败，避免 9 次无谓的 xdotool 超时
```

---

## 六、风险与依赖

### 6.1 技术风险

| 风险 | 概率 | 影响 | 缓解 |
|---|---|---|---|
| PriorityQueue 元组比较失败 | 低 | worker 崩溃 | `coro_factory` 不可比较，用 `seq` 序列号作为第二排序键，`(priority, seq)` 组合唯一，不会比较到 coro_factory |
| 父类 `_run` 与子类 `_run` 元组结构不一致 | 中 | 父类被误调用时解包失败 | 子类必须覆盖 `_run`；代码注释明确标注"覆盖父类"；单元测试验证子类 `_run` 被调用 |
| 父类 `__init__` 创建 `asyncio.Queue` 后被子类 `asyncio.PriorityQueue` 覆盖 | 低 | 内存短暂多出一个未使用 Queue 对象 | Python 属性遮蔽合法，旧 Queue 被 GC 回收，无副作用 |
| 优先级反转导致 HIGH 操作被 LOW 阻塞 | 中 | logout 等待 screenshot 完成 | 限制单次操作超时（已有 5s/30s），screenshot 入 LOW 但超时 10s |
| drain 阻塞 watchdog | 中 | autofix 延迟 | drain 超时 5s 后强制 kill，不无限等待 |
| drain 返回 True 后 worker 仍在 sleep | 低 | kill 时机略早于 sleep 结束 | 队列已空，worker sleep 结束后阻塞在 `get()` 上，不会执行新任务；kill 后 worker 执行失败被正常捕获 |
| 收口后 logout 等 HTTP 接口延迟增加 | 中 | 用户感知 | priority=HIGH 保证优先级，wait_timeout_ms 兜底 |
| `put_nowait` 与父类 `await put` 行为差异 | 低 | 满队时子类立即抛错，父类先检查再 put | 行为等价（父类也有前置 qsize 检查），子类更简洁 |
| `task_done()` 调用次数 | 低 | 计数器异常 | cancelled 分支和 finally 分支互斥（continue 跳过 finally），每个 `get()` 对应一次 `task_done()`，与父类一致 |
| metrics 并发读写 | 低 | 数据轻微不准 | asyncio 单线程事件循环，worker 与 HTTP handler 同线程，无需加锁；`asyncio.to_thread` 释放事件循环时不读写 `_metrics` |

### 6.2 依赖

- 依赖现有 `SendQueue` 实现稳定（已验证 16 个调用点）
- 依赖 `_ui_lock` 作为底层互斥（保持不变）
- 依赖 `asyncio.PriorityQueue`（Python 3.8+ 标准库，无外部依赖）

### 6.3 非目标

- **不实现优先级抢占**：xdotool 子进程不可中断，低优先级操作开始后必须等其完成
- **不实现优先级继承**：xdotool 子进程无法感知调用方优先级
- **不重命名 `SendQueue` 类**：保持向后兼容，UIActionScheduler 继承之
- **不修改 `_ui_lock`**：保持作为底层单命令互斥的第二道防线
- **不收口 LoginGuard / MessageStreamer**：它们是只读探测，无需入队

### 6.4 失败风暴问题与 fast-fail 机制

**问题场景**：当 watchdog kill 微信或 `wechat_restart` 完成后，send_queue 中可能仍有 N 个已入队的 send_text 任务。这些任务会按顺序执行，每个都因 `WINDOW_NOT_FOUND` 失败一次（直到 autostart 拉起新进程）。

**影响估算**：
- 100 个 send_text 任务排队，每个执行失败耗时 ~1s（含 5s xdotool 超时 + 异常处理）
- 微信 autostart 拉起需 ~5-10s
- 失败风暴持续：`min(N, autostart拉起前积压数) × 1s` ≈ 5-10s 内 5-10 个任务连续失败
- 客户端收到 5-10 个 503 错误，可能触发重试，进一步放大风暴

**fast-fail 机制设计**（**本方案可选实施，建议阶段 2 一并实施**）：

```python
class UIActionScheduler(SendQueue):
    def __init__(self, ...):
        super().__init__(...)
        # ...
        self._wechat_dead_until: float = 0.0  # 时间戳，在此之前所有任务直接 fast-fail

    def mark_wechat_dead(self, duration_sec: float = 10.0) -> None:
        """标记微信已死，期间所有新任务直接 fast-fail。
        
        供 watchdog kill / wechat_restart 调用：
        - kill 前调 mark_wechat_dead(15.0)，覆盖 autostart 拉起窗口
        - restart 完成后调 mark_wechat_dead(5.0)，覆盖新进程启动窗口
        """
        self._wechat_dead_until = time.monotonic() + duration_sec
        logger.warning(
            "[scheduler] mark_wechat_dead %.1fs, %d pending tasks will fast-fail",
            duration_sec, self._queue.qsize(),
        )

    async def _run(self) -> None:
        while True:
            priority, seq, coro_factory, future, custom_delay_ms = await self._queue.get()
            # ... cancelled 检查 ...
            
            # fast-fail 检查：微信已死期间所有任务直接失败
            if self._wechat_dead_until > time.monotonic():
                logger.info(
                    "[scheduler] fast-fail (wechat dead, %.1fs remaining, priority=%s)",
                    self._wechat_dead_until - time.monotonic(),
                    Priority(priority).name,
                )
                if not future.done():
                    future.set_exception(BridgeError(
                        code="WECHAT_NOT_READY",
                        message="微信进程未就绪（重启中），请稍后重试",
                        details={"retry_after": 5},
                    ))
                self._queue.task_done()
                continue  # 不延时，立即处理下一个
            
            # ... 正常执行流程 ...
```

**调用点**：
- `watchdog._autofix_wechat` kill 前调 `scheduler.mark_wechat_dead(15.0)`
- `routes/login.py wechat_restart` 开始时调 `scheduler.mark_wechat_dead(8.0)`
- `routes/diagnostic.py autofix_wechat_running` 同上

**注意事项**：
- `WECHAT_NOT_READY` 是新错误码，需在 `models/errors.py` 注册 HTTP 503 映射
- fast-fail 任务不计入 `executed_total`，应单独记 `fast_fail_total` 指标
- CRITICAL 任务（如 restart 本身）不应被 fast-fail 拦截，需在检查中排除：
  ```python
  if self._wechat_dead_until > time.monotonic() and priority > Priority.CRITICAL:
  ```

**替代方案对比**：

| 方案 | 优点 | 缺点 |
|---|---|---|
| fast-fail（推荐） | 立即拒绝，客户端快速收到错误并退避 | 需新增错误码 + 调用点埋点 |
| drain + cancel pending | 队列清空，无失败任务 | cancel 已入队 future 复杂，可能误取消正在执行的任务 |
| 不处理（保持现状） | 实现简单 | 5-10 个连续失败，客户端可能重试放大风暴 |

---

## 七、变更记录

| 版本 | 日期 | 修改人 | 摘要 |
|---|---|---|---|
| v1.0 | 2026-07-17 | - | 初稿，基于 SendQueue 调研设计 UIActionScheduler 统一调度方案 |
| v1.1 | 2026-07-17 | - | 深度复核：修正 task_done 互斥说明、put_nowait 语义、logout 前置 detect_login_state 处理、StatusResponse 模型扩展、激活已存在 Prometheus Gauge、drain 边界条件、metrics 线程安全 |
| v1.2 | 2026-07-18 | - | 深度调研优化：新增 1.4 双层保护模型（L1 _ui_lock vs L2 SendQueue）、1.5 调用点全景图（before/after）、1.6 HTTP 端点→优先级映射表、2.3.1 delay_ms 与优先级交互策略、5.1 关键场景时序图（4 个）、6.4 失败风暴问题与 fast-fail 机制（mark_wechat_dead）、UIActionScheduler 代码新增 mark_wechat_dead 方法与 _run fast-fail 检查、P1.1 detect_login_state 14 处散落调用分析与处理方案 |

---

## 八、实施前验证清单

实施前需确认以下事项，避免引入新问题：

### 8.1 代码复核清单

- [ ] `asyncio.PriorityQueue.put_nowait` 满时抛 `asyncio.QueueFull`（已确认，与 `asyncio.Queue` 行为一致）
- [ ] `asyncio.PriorityQueue` 的 `task_done()` / `join()` 语义与 `asyncio.Queue` 一致（已确认，继承关系）
- [ ] 元组 `(int, int, coro_factory, future, delay_ms)` 中 `seq` 单调递增保证唯一，不会比较到 `coro_factory`（已确认）
- [ ] 父类 `__init__` 创建的 `asyncio.Queue` 会被子类 `asyncio.PriorityQueue` 覆盖，旧对象无其他引用，GC 回收（已确认）
- [ ] 父类 `_run` 被子类覆盖，不会调用父类的 3 元组解包（已确认，代码注释标注）
- [ ] `_check_rate_limit` 继承父类，行为不变（已确认，子类不覆盖）
- [ ] `send_queue.start()` / `stop()` 继承父类，worker task 管理 不变（已确认）
- [ ] `pending_count()` 继承父类，返回 `self._queue.qsize()`（已确认，PriorityQueue 也有 qsize）

### 8.2 单元测试清单

实施时需编写以下单元测试（参考 `verify_bus.py` 的测试模式）：

```python
# test_ui_action_scheduler.py

async def test_backward_compat_enqueue():
    """enqueue 方法向后兼容，priority 默认 NORMAL。"""
    scheduler = UIActionScheduler(send_delay_ms=10, max_calls_per_sec=100)
    await scheduler.start()
    try:
        result = await scheduler.enqueue(lambda: asyncio.sleep(0.01, result="ok"))
        assert result == "ok"
        metrics = scheduler.get_metrics()
        assert metrics["executed_total"] == 1
        assert metrics["executed_by_priority"]["NORMAL"] == 1
    finally:
        await scheduler.stop()

async def test_priority_ordering():
    """CRITICAL 优先于 NORMAL 执行。"""
    scheduler = UIActionScheduler(send_delay_ms=0, max_calls_per_sec=100)
    await scheduler.start()
    try:
        # 先入队一个 NORMAL（会立即开始执行）
        normal_future = scheduler.enqueue(lambda: asyncio.sleep(0.1, result="normal"))
        # 再入队 CRITICAL 和 NORMAL
        critical_future = scheduler.execute(
            lambda: asyncio.sleep(0.01, result="critical"),
            priority=Priority.CRITICAL,
        )
        normal2_future = scheduler.execute(
            lambda: asyncio.sleep(0.01, result="normal2"),
            priority=Priority.NORMAL,
        )
        # CRITICAL 应先于 normal2 完成
        critical_result = await critical_future
        normal2_result = await normal2_future
        assert critical_result == "critical"
        assert normal2_result == "normal2"
        # 验证执行顺序：CRITICAL 在 normal2 之前
        assert scheduler.get_metrics()["executed_by_priority"]["CRITICAL"] == 1
    finally:
        await scheduler.stop()

async def test_drain_empty_queue():
    """空队列 drain 立即返回 True。"""
    scheduler = UIActionScheduler()
    result = await scheduler.drain(timeout=1.0)
    assert result is True

async def test_drain_with_pending():
    """有 pending 任务时 drain 等待完成。"""
    scheduler = UIActionScheduler(send_delay_ms=100)
    await scheduler.start()
    try:
        # 入队一个任务
        await scheduler.enqueue(lambda: asyncio.sleep(0.05, result="ok"))
        # drain 等待完成
        result = await scheduler.drain(timeout=2.0)
        assert result is True
    finally:
        await scheduler.stop()

async def test_drain_timeout():
    """任务执行超过 drain timeout 时返回 False。"""
    scheduler = UIActionScheduler(send_delay_ms=0)
    await scheduler.start()
    try:
        # 入队一个长任务
        scheduler.enqueue(lambda: asyncio.sleep(1.0, result="slow"))
        # drain 短超时
        result = await scheduler.drain(timeout=0.1)
        assert result is False
    finally:
        await scheduler.stop()

async def test_queue_full_rate_limited():
    """队列满时抛 RATE_LIMITED。"""
    scheduler = UIActionScheduler(send_delay_ms=1000, max_queue_size=2)
    await scheduler.start()
    try:
        # 填满队列（1 个执行中 + 2 个排队）
        scheduler.enqueue(lambda: asyncio.sleep(0.5))
        scheduler.enqueue(lambda: asyncio.sleep(0.01))
        scheduler.enqueue(lambda: asyncio.sleep(0.01))
        # 第 4 个应被拒绝
        with pytest.raises(BridgeError) as exc_info:
            await scheduler.enqueue(lambda: asyncio.sleep(0.01))
        assert exc_info.value.code == "RATE_LIMITED"
    finally:
        await scheduler.stop()

async def test_wait_timeout():
    """等待超时抛 TIMEOUT。"""
    scheduler = UIActionScheduler(send_delay_ms=1000, max_calls_per_sec=100)
    await scheduler.start()
    try:
        # 第一个任务慢
        scheduler.enqueue(lambda: asyncio.sleep(0.5))
        # 第二个任务等待超时
        with pytest.raises(BridgeError) as exc_info:
            await scheduler.enqueue(
                lambda: asyncio.sleep(0.01),
                wait_timeout_ms=100,  # 100ms 超时
            )
        assert exc_info.value.code == "TIMEOUT"
    finally:
        await scheduler.stop()

async def test_metrics_accuracy():
    """metrics 准确记录执行次数和优先级。"""
    scheduler = UIActionScheduler(send_delay_ms=0, max_calls_per_sec=100)
    await scheduler.start()
    try:
        await scheduler.execute(lambda: "a", priority=Priority.CRITICAL)
        await scheduler.execute(lambda: "b", priority=Priority.HIGH)
        await scheduler.execute(lambda: "c", priority=Priority.NORMAL)
        await scheduler.execute(lambda: "d", priority=Priority.LOW)
        metrics = scheduler.get_metrics()
        assert metrics["executed_total"] == 4
        assert metrics["executed_by_priority"]["CRITICAL"] == 1
        assert metrics["executed_by_priority"]["HIGH"] == 1
        assert metrics["executed_by_priority"]["NORMAL"] == 1
        assert metrics["executed_by_priority"]["LOW"] == 1
        assert metrics["pending_count"] == 0
    finally:
        await scheduler.stop()
```

### 8.3 集成测试清单

阶段 2 实施后需进行集成测试：

- [ ] 并发 30 个 `POST /api/send/text` + 1 个 `POST /api/login/logout`：logout 在所有 send 之前或之后执行，不穿插
- [ ] `POST /api/screenshot` 与 `POST /api/send/text` 并发：screenshot 串行等待
- [ ] watchdog autofix 触发时 send_queue 有 pending：先 drain 再 kill
- [ ] `GET /api/status` 返回 `ui_scheduler` 字段且 `executed_by_priority` 计数正确
- [ ] `/metrics` 端点 `woc_send_queue_pending` Gauge 不再恒为 0

### 8.4 回归测试清单

阶段 1 实施后需验证现有功能不退化：

- [ ] `POST /api/send/text` 正常发送（16 个 enqueue 调用点之一）
- [ ] `POST /api/friends/accept` 正常通过好友（friend_watcher + routes/contacts 共用 enqueue）
- [ ] `POST /api/moments/publish` 正常发朋友圈（routes/moments enqueue）
- [ ] BatchWorker 群发正常串行（间接经 orchestrator → enqueue）
- [ ] `GET /api/status` 的 `send_queue_pending` 字段仍正确