OpenProgram · 设计文档

报错与超时机制（现状梳理）

范围：一次 runtime.exec() 从发起到失败/超时的完整路径——重试、退避、连接/流超时、错误分类、外层 watchdog。 目的：先把现状写清楚再优化。优化项在文末（§8）单列并标注实现状态与对应 commit。配套：docs/design/llm-fault-tolerance.md（跨框架对比）、error-retry.md。

1 三层超时职责

系统里有三种语义不同的「超时」，分属不同层、由不同代码负责。把它们混在一起是大多数困惑的来源。

2 完整调用栈

从 benchmark 一路到网络 I/O。每层右下角标注它自己持有的超时/重试控制。注意有 三层独立的重试循环（locator、exec、stream_retry），彼此不共享 wall-clock。

3 已有的超时防御（已 armed）

这些都已经在生效，默认值全部可经 env 覆盖。集中定义在 providers/utils/timeouts.py 与 http_client.py。

4 exec 重试状态机

一次 exec() 内部的重试逻辑。关键：deadline 检查只发生在两次 _call 之间（虚线框），无法打断正在执行的 _call。

# runtime.py:746–818（精简）
_deadline = start + timeout_s   # timeout_s=None ⇒ _deadline=None ⇒ 整段失效
for attempt in range(max_retries):          # 默认 6（_default_max_retries, :58）

    ┌── 软 deadline 检查（仅 attempt 之间）─────────────┐
    if _deadline and now() >= _deadline:           # :754
        raise LLMError(reason=TIMEOUT, retryable=False)
    └──────────────────────────────────────────────────┘

    try:
        reply = self._call(...)      # :771 同步阻塞，无 timeout 入参；卡这里时上面的检查到不了
        break
    except (TypeError, NotImplementedError):
        raise                       # 编程错误，不重试
    except Exception as e:           # :780 ← 这里吞掉一切，包括外来的 TimeoutError
        permanent = _is_permanent_error(e)   # :782 只匹配图片/auth marker
        if permanent or attempt == max_retries-1:
            raise _build_llm_error(...)   # → LLMError(reason, retryable, cause, …)
        sleep_s = _retry_sleep_seconds(attempt)  # 1.5·2^n，±25% 抖动；attempt5 ≈ 48s（:81）
        if _deadline and now()+sleep_s >= _deadline:  # :801 退避会越界就提前判 TIMEOUT
            raise LLMError(reason=TIMEOUT, retryable=False)
        time.sleep(sleep_s)          # :818

_is_permanent_error 只认两类 runtime.py:104–120

marker 列表只有：not a valid image / invalid image / image data is not / login expired / login failed / re-auth / unauthorized / invalid api key。任何超时类异常都不命中 → permanent=False → 会被重试。这正是外层 SampleTimeoutError 被当 transient 吃掉的直接原因。

5 核心缺陷：三层重试相乘，无人封顶 wall-clock

持续 ConnectError（死路由 / VPN 黑洞 / proxy 不通，日志即 openai-codex stream retry … ConnectError）时，三层循环逐层相乘，没有任何一层用 wall-clock 封顶：

6 watchdog 被吞掉的时序

ScreenSpot 用 signal.alarm 想在 sample 总预算到点时硬停，但它抛的异常正好撞进上面两层的 except Exception。

7 错误分类与 retryable 判定

exec 放弃时抛的是结构化 LLMError（errors.py:62），已经带够了上层精确计分所需的字段——上层不该一律记成 wrong_format。

classify_error 判定顺序 errors.py:191–258

注意：override_reason=TIMEOUT 的 deadline 命中一律 retryable=False（runtime.py:170–176）；其余「预算耗尽但类型本可重试」保持 retryable=True，含义是「换个新预算可再试」，不是「立刻重试」。

8 优化项（实现状态）

两条线并行、职责不同：框架侧 #1–#4 让任何调用方（channels worker、web turn、benchmark）都不被嵌套重试拖死；harness 侧 #5 负责 sample-level 计分与可靠 watchdog。子进程不替代框架修复，框架修复也不免除 runner 的 watchdog。#1–#4 已在框架 4e64ac95 落地，#5 在 harness 74bfd06 落地（子进程隔离暂缓）；#6 暂缓。