241 lines
13 KiB
Markdown
241 lines
13 KiB
Markdown
---
|
||
title: "Async Generator Deadlock: yield Must Precede await When await Depends on the Yielded Event"
|
||
date: 2026-07-06
|
||
category: runtime-errors
|
||
module: core/react.py
|
||
problem_type: runtime_error
|
||
component: assistant
|
||
symptoms:
|
||
- "Deadlock during autonomy pause in ReActEngine — agent loop hangs indefinitely and never resumes"
|
||
- "Frontend never receives the pause event, so the user has no UI to send a resume message"
|
||
- "await resume_handler blocks forever waiting for a resume message that can never arrive"
|
||
root_cause: async_timing
|
||
resolution_type: code_fix
|
||
severity: critical
|
||
related_components:
|
||
- "chat (WebSocket handler delivering pause events to frontend)"
|
||
- "experts (expert team autonomy pause integration)"
|
||
tags: [async-generator, deadlock, react-engine, autonomy-pause, async-timing, python]
|
||
---
|
||
|
||
# Async Generator Deadlock: yield Must Precede await When await Depends on the Yielded Event
|
||
|
||
## Problem
|
||
|
||
ReActEngine 的自主暂停机制（`_check_autonomy_pause`）存在 P0 级死锁：当 agent 在 ReAct 循环中触发超时/失败条件需要请求用户接管时，`autonomy_paused` 事件永远无法送达前端，导致 `resume_handler` 永久阻塞，agent 主循环卡死。
|
||
|
||
根本原因是 async generator 中 `yield` 与 `await` 的顺序错误——当 `await` 依赖被 `yield` 的事件已被消费时，`yield` 必须先于 `await` 执行。
|
||
|
||
## Symptoms
|
||
|
||
- 在 IQ-Boost 自主模式触发暂停条件后，前端永远收不到 `autonomy_paused` 事件
|
||
- WebSocket 客户端无任何错误，但 agent 主循环卡死，不再产生新 step
|
||
- `resume_handler` 调用永远不返回（前端永远收不到事件，因此也永远发不出 `resume` 消息）
|
||
- 服务端无异常日志，表现为「静默挂起」——典型的死锁症状，最难定位
|
||
- 重启服务后才能恢复，但下一次触发暂停条件时再次复现
|
||
|
||
## What Didn't Work
|
||
|
||
在定位死锁根因前，尝试过若干方向，均未奏效：
|
||
|
||
1. **怀疑 `resume_handler` Future 未被正确 resolve**：检查 WebSocket loop 的 `resume` 消息处理逻辑，发现 resolve 路径正确——但问题是前端从未发送 `resume` 消息，所以根本走不到 resolve。这一方向浪费了时间，因为它假设事件已送达。
|
||
|
||
2. **怀疑 `pending_autonomy_resumes` 注册时机问题**：尝试在 `await resume_handler` 之前提前注册 Future，但死锁依旧——因为问题不在注册时机，而在事件是否送达消费端。
|
||
|
||
3. **怀疑 `autonomy_paused` 事件被 list 缓冲导致延迟**：原实现将事件先 append 到 list，再在 `await` 之后从 list 中 yield。一度尝试在 `await` 之前先 yield list 中的事件，但由于 `for _pev in pause_events` 循环位于 `await` 之后，这种「提前 yield」并未真正改变事件送达顺序。这一尝试离根因最近，但因为仍在原方法内调整顺序，无法干净地表达「先发事件、再阻塞等待」的语义。
|
||
|
||
4. **通过加日志排查**：在 `await resume_handler` 前后加日志，确认 `await` 之前日志打出，之后日志从未打出——确认是 `await` 处永久阻塞。但日志无法解释「为什么前端不发 resume」，直到审视事件流方向才发现事件根本没送达。
|
||
|
||
关键转折点：意识到 `resume_handler` 是一个**反向信道**——它等待的事件，正是由本 generator `yield` 出去的事件触发的。这构成了循环依赖，而打破循环依赖的唯一方式是保证 `yield` 在 `await` 之前完成。
|
||
|
||
## Solution
|
||
|
||
将原本耦合在一个 async generator 中的「检测」与「等待恢复」拆分为两个职责单一的方法，并在调用方显式控制 `yield` 与 `await` 的顺序。
|
||
|
||
### 原实现（死锁）
|
||
|
||
```python
|
||
# src/agentkit/core/react.py — 原方法（已删除）
|
||
async def _check_autonomy_pause(self, step, progress, resume_handler):
|
||
"""检测自主暂停条件，yield 暂停事件并等待恢复。"""
|
||
pause_events = []
|
||
# ... 检测 timeout/failure 条件 ...
|
||
if should_pause:
|
||
pause_events.append(
|
||
ReActEvent(event_type="autonomy_paused", step=step, data=event_data)
|
||
)
|
||
# 致命错误：先 await，后 yield
|
||
should_continue = await resume_handler(resume_token, reason)
|
||
for _pev in pause_events:
|
||
yield _pev # 永远走不到这里——await 已死锁
|
||
return should_continue, pause_events
|
||
```
|
||
|
||
调用方：
|
||
|
||
```python
|
||
# 调用方（死锁）— yield 发生在 handler 返回之后，为时已晚
|
||
should_continue, pause_events = await self._check_autonomy_pause(
|
||
step, _progress, resume_handler
|
||
)
|
||
for _pev in pause_events:
|
||
yield _pev # 事件在 await 之后才送达消费端——死锁
|
||
if not should_continue:
|
||
break
|
||
```
|
||
|
||
### 修复后（拆分 + 显式顺序）
|
||
|
||
```python
|
||
# src/agentkit/core/react.py — 拆分后的纯检测方法（非阻塞、无 yield、无 await）
|
||
def _detect_autonomy_pause(self, step, progress) -> tuple[str, str, dict] | None:
|
||
"""纯检测：返回 (reason, resume_token, event_data) 或 None。
|
||
不 await、不 yield——保持纯函数语义，便于在调用方控制顺序。"""
|
||
# ... 检测 timeout/failure 条件 ...
|
||
if not should_pause:
|
||
return None
|
||
return (reason, resume_token, event_data)
|
||
|
||
|
||
# src/agentkit/core/react.py — 拆分后的纯阻塞方法
|
||
async def _await_autonomy_resume(
|
||
self, resume_token: str, reason: str, resume_handler
|
||
) -> bool:
|
||
"""阻塞等待用户恢复。返回 True 表示已恢复，False 表示已取消。
|
||
由调用方保证在 yield 事件之后才调用本方法。"""
|
||
return await resume_handler(resume_token, reason)
|
||
```
|
||
|
||
调用方（关键修复点——`yield` 必须在 `await` 之前）：
|
||
|
||
```python
|
||
# src/agentkit/core/react.py — 主 ReAct 循环（修复后）
|
||
pause_info = self._detect_autonomy_pause(step, _progress)
|
||
if pause_info is not None:
|
||
reason, resume_token, event_data = pause_info
|
||
# 1. 先 yield：事件送达消费端（chat.py 的 async for 循环）
|
||
yield ReActEvent(
|
||
event_type="autonomy_paused", step=step, data=event_data
|
||
)
|
||
# 2. 后 await：此时消费端已转发事件给 WebSocket 客户端，
|
||
# 前端收到 autonomy_paused 后才会发送 resume，Future 才会被 resolve
|
||
should_continue = await self._await_autonomy_resume(
|
||
resume_token, reason, resume_handler
|
||
)
|
||
if not should_continue:
|
||
break
|
||
```
|
||
|
||
## Why This Works
|
||
|
||
修复的核心是恢复正确的因果链。原实现的因果链是断开的：
|
||
|
||
```
|
||
原（断开）：await resume_handler → （永远阻塞，因为）→ yield 事件 → 前端 resume → resolve Future
|
||
↑ 这一步永远到不了
|
||
```
|
||
|
||
修复后的因果链是闭合的：
|
||
|
||
```
|
||
修复（闭合）：yield 事件 → 消费端转发 → 前端收到 autonomy_paused
|
||
→ 前端发送 resume → WebSocket loop resolve Future
|
||
→ _await_autonomy_resume 返回 → 主循环继续
|
||
```
|
||
|
||
技术上，async generator 的 `yield` 是一个**协作点**：它将控制权交还给消费方（本例中是 `chat.py` 的 `async for` 循环），消费方转发事件给 WebSocket 客户端，客户端再把事件推到浏览器。只有当这条链路走完，前端的 `resume` 消息才有可能发回。原实现将 `yield` 放在 `await` 之后，等于要求「先收到 resume，再发送暂停事件」——这是因果倒置。
|
||
|
||
拆分为 `_detect_autonomy_pause`（纯函数）和 `_await_autonomy_resume`（纯阻塞）的好处不止修复 bug：
|
||
|
||
1. **顺序显式化**：调用方代码本身就说明了「先 yield，后 await」的契约，任何后续修改都难以意外打乱顺序。
|
||
2. **可测试性**：`_detect_autonomy_pause` 是纯函数，可以直接断言输入输出，无需 mock 异步环境；`_await_autonomy_resume` 只验证恢复/取消两条路径。
|
||
3. **关注点分离**：检测逻辑（何时暂停）与等待逻辑（如何恢复）独立演化，例如未来支持「超时自动恢复」只需改 `_await_autonomy_resume`。
|
||
|
||
## Prevention
|
||
|
||
### 1. 通用规则：反向信道场景下 yield 必须先于 await
|
||
|
||
当 async generator 中存在「await 等待的事件由本 generator yield 出去触发」的反向信道时，`yield` 必须先于 `await`。这扩展了项目已有的异步生成器安全规则。
|
||
|
||
在 AGENTS.md 已有规则的基础上补充：
|
||
|
||
> 异步生成器安全（扩展）：在 `async def` 中禁止在第一个 `yield` 之前使用 `return`；并且当 `await` 依赖被 `yield` 的事件已被消费时，`yield` 必须先于 `await`。
|
||
|
||
### 2. 拆分检测与阻塞，让顺序契约显式
|
||
|
||
凡是「先发事件、后等响应」的 async generator，优先考虑拆分为：
|
||
|
||
- 一个**纯检测方法**（同步、无 await、无 yield），返回决策结果
|
||
- 一个**纯阻塞方法**（async，只 await handler），由调用方在 yield 之后调用
|
||
|
||
这种拆分让「先 yield 后 await」从隐式约定变成显式代码结构，code review 时一目了然。
|
||
|
||
### 3. Code review 检查项
|
||
|
||
审查任何包含 `yield` 与 `await` 的 async generator 时，问自己一个问题：
|
||
|
||
> 这个 generator 里的某个 `await`，是否依赖于消费端已经收到了此前 `yield` 出去的事件？
|
||
|
||
如果答案是「是」，则必须保证 `yield` 在该 `await` 之前执行。常见的反向信道场景：
|
||
|
||
- 用户确认/接管（本例）
|
||
- 资源就绪信号（yield 请求 → await 就绪）
|
||
- 跨 agent handoff（yield handoff 事件 → await 对端 ack）
|
||
|
||
### 4. 测试：mock 消费端验证事件顺序
|
||
|
||
为「yield 后 await」契约写一个最小可执行检查（遵循 ponytail 规则——最小可失败的断言，无框架）：
|
||
|
||
```python
|
||
# tests/unit/test_react_autonomy_pause.py — 最小自检
|
||
import asyncio
|
||
import pytest
|
||
|
||
async def _consume_then_resume(agent, steps, resume_handler):
|
||
"""模拟 chat.py 消费端：先收到 autonomy_paused 事件，才 resolve resume。"""
|
||
received_pause = asyncio.Event()
|
||
resume_future = asyncio.get_event_loop().create_future()
|
||
|
||
async def fake_handler(token, reason):
|
||
# 必须等消费端确认收到事件后才 resolve
|
||
await received_pause.wait()
|
||
return True
|
||
|
||
events = []
|
||
async for ev in agent.run_stream(steps):
|
||
events.append(ev)
|
||
if ev.event_type == "autonomy_paused":
|
||
received_pause.set() # 模拟前端收到事件后发 resume
|
||
resume_future.set_result(True)
|
||
|
||
# 断言：autonomy_paused 必须出现在事件流中，且 run_stream 必须能正常结束
|
||
# （而非死锁挂起——pytest 的 asyncio 超时会捕获死锁）
|
||
assert any(ev.event_type == "autonomy_paused" for ev in events)
|
||
```
|
||
|
||
这个检查在原实现下会因为 `await asyncio` 超时而失败（死锁），在修复后通过——正是「最小可失败的检查」。
|
||
|
||
### 5. 项目规则联动
|
||
|
||
本学习扩展了 `.trae/rules/project_rules.md` 中已记录的异步生成器安全规则。原规则只覆盖「第一个 yield 之前不能 return」这一类问题，本学习补充了「yield 与 await 的顺序依赖」这一类。两条规则应一起记忆：
|
||
|
||
- **第一类**（已有）：`return` 在第一个 `yield` 之前 → 函数被识别为协程而非 async generator
|
||
- **第二类**（本学习）：`await` 在 `yield` 之前，且 `await` 依赖被 `yield` 的事件 → 死锁
|
||
|
||
## Related Issues
|
||
|
||
- **PR #27**（`feat/agent-iq-boost`）：本 bug 的引入与修复均在该分支完成
|
||
- **AGENTS.md > 异步生成器安全**：项目级规则，本学习为其扩展项
|
||
- **`.trae/rules/project_rules.md > Python Async Generator Safety`**：第一类规则的完整说明与 `return; yield` 模式
|
||
- **`src/agentkit/core/react.py`**：受影响文件，`_detect_autonomy_pause` 与 `_await_autonomy_resume` 的当前实现位置
|
||
- **`src/agentkit/server/routes/chat.py`**：消费端，`async for` 循环转发 `autonomy_paused` 事件至 WebSocket 客户端
|
||
- **根因类别**：`async_timing`——async generator 中 `yield` 与 `await` 的顺序在存在依赖时具有决定性
|
||
|
||
### 相邻学习（同一 execute_stream 合约）
|
||
|
||
以下文档覆盖 `ReActEngine.execute_stream()` async generator 的不同不变量，与本学习互补：
|
||
|
||
- [streaming-event-contract-residuals.md](../integration-issues/streaming-event-contract-residuals.md) — CancellationToken 注册对称性（execute_stream 绕过 BaseAgent.execute() 的 _active_tokens dict，破坏协作式取消）
|
||
- [streaming-event-whitelist-and-accumulation.md](./streaming-event-whitelist-and-accumulation.md) — token + final_answer 双重累积、WS 事件白名单、async generator 中的 except-Exception 作用域
|
||
- [long-horizon-reliability-code-review-fixes.md](../logic-errors/long-horizon-reliability-code-review-fixes.md) — execute() 入口未调用 reset() 导致状态隔离失败
|