Lesson 03 — 超时、熔断与诚实降级

# tools.py 现状
async def web_search(query, max_results=None):
    try:
        result = await asyncio.wait_for(...)
        return result
    except asyncio.TimeoutError:
        return f"搜索 '{query}' 超时（{settings.search_timeout}s）。可换关键词或稍后重试。"
    except Exception as e:
        return f"搜索 '{query}' 失败（{type(e).__name__}: {e}）。可换关键词重试。"

现状故障链：
  web_search 超时 → 返回 "搜索超时" 字符串
       ↓
  researcher 把它当 finding 加入 findings
       ↓
  summarize 把 "搜索超时" 总结进摘要
       ↓
  writer 把 "搜索超时" 写进报告当事实 ☠️

# tools.py L03 新增
async def web_search_structured(query, max_results=None) -> dict:
    """返回结构化结果：{"status": "ok"|"degraded"|"failed", "content": str, "reason": str}"""
    ...
    except asyncio.TimeoutError:
        return {"status": "degraded", "content": "", "reason": f"搜索超时（{timeout}s）"}

# nodes.py researcher（enable_circuit_breaker 时）
sr = await web_search_structured(subtopic)
if sr["status"] == "ok":
    web_raw = sr["content"]
else:
    web_raw = ""
    failed_subtopic = f"{subtopic}（{sr['reason']}）"  # 上报失败
    ...
if failed_subtopic is not None:
    return {"findings": [], "failed_subtopics": [failed_subtopic]}  # 不产出污染 finding

# nodes.py writer
failed_subs = state.get("failed_subtopics", [])
if failed_subs:
    report += f"\n\n⚠️ **检索降级声明**：以下 {len(failed_subs)} 个子题检索失败，本报告未涵盖：\n{decl}"

雪崩放大器：
  持续故障（搜索服务挂了）+ 无限重试
    = 每个请求都等满 超时(15s) × 重试次数(3) = 45s
    = 并行 3 个子题 × 45s = 135s 卡死
    = 持续故障期间所有请求堆积 → 雪崩

  熔断器：连续 N 次失败 → 打开 → 快速失败（不等超时）
    = 第 4 次起 0ms 返回 degraded
    = 阻断雪崩放大

         连续 fail_threshold 次失败
   ┌──────────────────────────────┐
   │                              ▼
 CLOSED ◄────试探成功──── HALF_OPEN ────冷却结束──── OPEN
 (放行)                      ▲                            │
   │                        │                    试探失败 │
   └──成功清零失败计数────────┘                            │
                              └──────────────────────────┘
                                 （重新计时，继续熔断）

browser（慢深贵，详情页取证）
   │ 失败/未启用
   ▼
web_search（快浅便宜，搜索摘要）
   │ 失败/超时
   ▼
跳过该子题 + 报告声明「检索失败」（不编造内容）

cd portfolio-projects/research-assistant
python ../../agent-ops-lessons/03_breaker_degrade/code.py

cd portfolio-projects/research-assistant

# 1. 全部测试绿（156 + 15 = 171）
python -m pytest -q
# 预期：171 passed

# 2. 开关关时行为 = 现状（web_search 字符串返回不变）
python -m pytest tests/test_tools.py tests/test_nodes.py -q
# 预期：全绿（web_search_structured 不影响 web_search）

# 3. 开熔断后超时返回 degraded（非字符串）
python -c "
import asyncio
from research_assistant import config
config.settings.__dict__['enable_circuit_breaker'] = False
config.settings.__dict__['search_timeout'] = 1
from research_assistant.tools import web_search_structured
from research_assistant import tools
import time
tools._ddgs_search = lambda q,n: (time.sleep(2), '不该到这')[1]
r = asyncio.run(web_search_structured('q'))
print(r['status'], r['content'] == '')
"
# 预期：degraded True（超时返回 degraded + content 空，不污染）