1. 引言:为什么 2026 年还要认真研究 errno

在 Python 生态里,errno 是一个"存在感极低、重要性极高"的模块。它只有几十行代码,导出的常量却支撑着整个 CPython 解释器与操作系统之间的错误传递机制。绝大多数开发者第一次接触它,是在一段 try/except OSError as e: if e.errno == errno.EEXIST: 的代码里;而真正理解它的人,往往是在生产环境被 EINTR、EAGAIN、ENOSPC 这些"幽灵错误"折磨过之后。

本报告以 errno 为切入点,做三件事:

  1. 解析:从 POSIX 与 Linux 内核的错误码约定出发,讲清 errno 在 C 层、CPython 层、Python 应用层的三次"语义跃迁"。
  2. 亮点:梳理 Python 3.3+ 以来 OSError 体系的重构(PEP 3151)、errno 与 ExceptionGroup、add_note 的现代组合用法,以及跨平台差异的工程化处理。
  3. 复杂工程:把 errno 放进一个真实可运行的"机器人 Agent 容错框架"中——包含 Robot Agent、embedding 检索、copilot 决策、harness 测试夹具,展示错误码如何成为智能体可靠性的地基。

全文代码均可直接复制运行(Python 3.11+,部分示例标注了 3.12 特性),并尽量给出可观测的输出。

2. errno 的本质:一个被约定出来的全局变量

2.1 C 语言中的 errno

在 POSIX 标准中,errno 并不是一个普通的全局变量,而是一个宏,通常展开为线程局部存储(TLS)中的某个位置:

#include <errno.h>
#include <stdio.h>
#include <string.h>

int main(void) {
    FILE *fp = fopen("/definitely/not/exist", "r");
    if (fp == NULL) {
        // errno 在失败瞬间被设置
        printf("errno = %d\n", errno);          // 2
        printf("strerror = %s\n", strerror(errno)); // No such file or directory
    }
    return 0;
}

关键约定有三条,理解它们才能理解 Python 侧的行为:

  • 只有失败时才被设置:成功的系统调用不会清零 errno。所以"先检查 errno 再判断是否失败"是错误写法。
  • 必须立即读取:任何后续的库函数调用(包括 printf)都可能覆盖它。
  • 线程安全靠 TLS:多线程下每个线程有独立的 errno,这是 POSIX.1-2001 之后的强制要求。

2.2 错误码的编号并不统一

这是跨平台工程中第一个大坑。EAGAIN 在 Linux x86-64 上是 11,在 macOS 上是 35;EWOULDBLOCK 在 Linux 上与 EAGAIN 同值,在部分 BSD 上不同。因此永远不要硬编码数字:

import errno

# 错误示范
if e.errno == 11:
    ...

# 正确示范
if e.errno in (errno.EAGAIN, errno.EWOULDBLOCK):
    ...

Python 的 errno 模块在导入时通过 C 扩展 _errno 从当前平台的 <errno.h> 中读取真实值,因此它天然是"平台正确"的。

2.3 Python errno 模块的结构

import errno

# 1. 常量:int 类型
print(type(errno.ENOENT), errno.ENOENT)      # <class 'int'> 2

# 2. errorcode:编号 -> 名称 的映射
print(errno.errorcode[2])                     # ENOENT

# 3. 反向查找:名称 -> 编号(通过 getattr)
print(getattr(errno, "ENOENT"))               # 2

# 4. 平台差异:某些常量只在特定平台存在
print(hasattr(errno, "ENOTSUP"))              # True (Linux)
print(hasattr(errno, "EWOULDBLOCK"))          # True

errno.errorcode 是一个普通 dict,非常适合做日志美化:

import errno

def errno_name(code: int) -> str:
    """把数字错误码翻译成可读名称,未知则返回 UNKNOWN。"""
    return errno.errorcode.get(code, f"UNKNOWN({code})")

print(errno_name(2))    # ENOENT
print(errno_name(9999)) # UNKNOWN(9999)

3. 从 errno 到 OSError:CPython 的语义跃迁

3.1 三次跃迁的路径

当一次 open() 失败时,错误信息经历了这样的旅程:

内核返回 -1 并设置 errno

CPython C 层读取 errno

构造 OSError 实例

填充 errno / strerror / filename 属性

Python 层 except OSError 捕获

在 Python 3.3 之前,这里会分裂成 IOError、OSError、WindowsError、socket.error 等多个类型,判断起来极其痛苦。PEP 3151 之后,它们统一为 OSError,并引入了按 errno 自动派生的子类。

3.2 PEP 3151:错误码到异常类的映射表

CPython 内部维护了一张映射表,把常见 errno 映射到更具体的异常子类:

errno异常子类典型场景
ENOENTFileNotFoundError文件不存在
EEXISTFileExistsError文件已存在
EACCES / EPERMPermissionError权限不足
EISDIRIsADirectoryError对目录做文件操作
ENOTDIRNotADirectoryError对文件做目录操作
EINTRInterruptedError系统调用被信号打断
ETIMEDOUTTimeoutError超时
ECONNREFUSEDConnectionRefusedError连接被拒绝
EAGAINBlockingIOError非阻塞 IO 未就绪

这意味着优先捕获具体子类,比判断 errno 更 Pythonic:

# 推荐:语义化捕获
try:
    with open("/tmp/robot_state.json") as f:
        state = f.read()
except FileNotFoundError:
    state = "{}"
except PermissionError:
    raise RuntimeError("机器人状态文件权限异常,请检查运行用户") from None

# 兼容写法:需要区分同子类下的不同 errno 时
import errno
try:
    ...
except OSError as e:
    if e.errno == errno.ENOSPC:
        raise RuntimeError("磁盘已满,无法写入机器人日志") from e
    raise

3.3 OSError 的属性全景

import errno, os

try:
    os.open("/root/secret.txt", os.O_RDONLY)
except OSError as e:
    print("errno   :", e.errno)        # 13
    print("strerror:", e.strerror)     # Permission denied
    print("filename:", e.filename)     # /root/secret.txt
    print("args    :", e.args)         # (13, 'Permission denied')
    print("repr    :", repr(e))        # PermissionError(13, 'Permission denied')

注意 e.args 只有两个元素,filename 是单独属性。序列化日志时建议显式取字段,而不是 str(e)。

4. 亮点一:errno 在现代 Python 中的组合技

4.1 与 ExceptionGroup 结合:批量 IO 的聚合错误

Python 3.11 引入 ExceptionGroup,非常适合"批量操作部分失败"的场景。机器人 Agent 常常需要同时读取多个传感器文件:

import errno
from pathlib import Path

def read_all_sensors(paths: list[Path]) -> dict[str, str]:
    results, errors = {}, []
    for p in paths:
        try:
            results[p.name] = p.read_text()
        except OSError as e:
            errors.append(e)
    if errors:
        raise ExceptionGroup("部分传感器读取失败", errors)
    return results

# 使用
try:
    data = read_all_sensors([Path("/tmp/lidar.txt"), Path("/tmp/camera.txt")])
except* FileNotFoundError as eg:
    print(f"{len(eg.exceptions)} 个传感器文件缺失")
except* PermissionError as eg:
    print(f"{len(eg.exceptions)} 个传感器文件无权限")

except* 按异常类型分流,比手写 if e.errno == ... 清晰得多。

4.2 与 add_note 结合:给错误码补充上下文

PEP 678(3.11)的 add_note 让错误码可以携带业务上下文:

import errno, os

def safe_mkdir(path: str) -> None:
    try:
        os.makedirs(path, exist_ok=True)
    except OSError as e:
        e.add_note(f"目标路径: {path}")
        e.add_note(f"错误码名称: {errno.errorcode.get(e.errno, 'UNKNOWN')}")
        e.add_note("建议: 检查磁盘配额与父目录权限")
        raise

try:
    safe_mkdir("/proc/forbidden/dir")
except OSError as e:
    print(e)
    for note in e.__notes__:
        print("  note:", note)

输出中会附带三条 note,排障时信息量远超原始 strerror。

4.3 与 retry 结合:EINTR 与 EAGAIN 的正确重试

这是工程中最容易写错的地方。EINTR 表示"被信号打断,可以立即重试";EAGAIN 表示"资源暂时不可用,应等待后重试"。二者语义不同:

import errno, time, socket

def recv_with_retry(sock: socket.socket, size: int = 4096,
                    max_retries: int = 5) -> bytes:
    for attempt in range(max_retries):
        try:
            return sock.recv(size)
        except InterruptedError:
            # EINTR:信号打断,立即重试,不计入退避
            continue
        except BlockingIOError:
            # EAGAIN:非阻塞未就绪,指数退避
            time.sleep(0.01 * (2 ** attempt))
            continue
        except ConnectionResetError:
            raise
    raise TimeoutError(f"重试 {max_retries} 次仍未收到数据")

注意 InterruptedError 在 Python 3.5+ 中,CPython 已经对多数系统调用做了自动重试(PEP 475),所以显式处理 EINTR 的场景已经大幅减少,但在自定义 C 扩展或 signal.set_wakeup_fd 场景下仍需注意。

4.4 跨平台差异的工程化封装

Windows 的 errno 与 POSIX 差异巨大(例如 WSAECONNREFUSED = 10061)。一个健壮的封装应该做"语义归一化":

import errno, sys

# 语义归一化表:把平台差异收敛到业务语义
_TRANSIENT = {
    errno.EAGAIN, errno.EWOULDBLOCK, errno.EINTR,
    errno.ETIMEDOUT, errno.EBUSY,
}
_NOT_FOUND = {errno.ENOENT, errno.ENOTDIR}
_PERMISSION = {errno.EACCES, errno.EPERM}

def classify_os_error(e: OSError) -> str:
    """把 OSError 归类为业务可用的语义标签。"""
    code = e.errno
    if code in _TRANSIENT:
        return "transient"      # 可重试
    if code in _NOT_FOUND:
        return "not_found"      # 资源缺失
    if code in _PERMISSION:
        return "permission"     # 权限问题
    if code == errno.ENOSPC:
        return "no_space"       # 磁盘满
    return "unknown"

# 验证
for code in (errno.EAGAIN, errno.ENOENT, errno.EACCES, errno.ENOSPC):
    fake = OSError(code, "x")
    print(code, "->", classify_os_error(fake))

这个 classify_os_error 就是后续 Agent 容错框架的"语义入口"。

5. 亮点二:errno 在可观测性中的价值

5.1 结构化日志中的错误码

生产环境里,errno 是**低基数(low cardinality)**指标,非常适合做 Prometheus 标签:

import errno, logging, json

logger = logging.getLogger("robot")

def log_os_error(e: OSError, context: dict) -> None:
    payload = {
        "errno": e.errno,
        "errno_name": errno.errorcode.get(e.errno, "UNKNOWN"),
        "strerror": e.strerror,
        "filename": e.filename,
        "semantic": classify_os_error(e),
        **context,
    }
    logger.error(json.dumps(payload, ensure_ascii=False))

try:
    open("/tmp/nope", "r")
except OSError as e:
    log_os_error(e, {"robot_id": "R-001", "task": "load_config"})

输出形如:

{"errno": 2, "errno_name": "ENOENT", "strerror": "No such file or directory", "filename": "/tmp/nope", "semantic": "not_found", "robot_id": "R-001", "task": "load_config"}

5.2 错误码分布是"系统健康度"的指纹

一个有趣的工程观察:errno 的分布形态能反映系统状态。

  • EAGAIN 占比突增 → 下游服务变慢或连接池耗尽;
  • ENOSPC 出现 → 磁盘即将写满,需立即告警;
  • ECONNRESET 占比上升 → 网络抖动或对端重启;
  • EMFILE 出现 → 文件描述符泄漏。

因此建议在 Agent 的 harness 中内置一个"错误码直方图",作为回归测试的断言依据。

6. 复杂工程:Robot Agent 容错框架

下面进入本报告的核心部分。我们要构建一个可运行的机器人 Agent 框架,它把 errno 作为底层错误语义,向上支撑 embedding 检索、copilot 决策、harness 测试,形成完整的可靠性闭环。

6.1 整体架构

保障层 Harness

智能层 Agent

错误语义层 errno

感知层 Perception

传感器读取

文件/网络 IO

classify_os_error

RetryPolicy

CircuitBreaker

Embedding 检索

Copilot 决策

Tool 调用

故障注入

错误码直方图

回归断言

设计要点:

  • 错误语义层是唯一入口:所有 OSError 必须经过 classify_os_error 归一化,禁止在业务层直接判断数字。
  • 重试与熔断分离:transient 走重试,permission/not_found 直接失败,unknown 走熔断保护。
  • Agent 层不感知 errno:Agent 只看到 transient/not_found 等语义标签,便于替换底层实现。

6.2 错误语义层实现

# errno_layer.py
from __future__ import annotations

import errno
import time
import logging
from dataclasses import dataclass, field
from enum import Enum
from typing import Callable, TypeVar

logger = logging.getLogger("robot.errno")

class Semantic(str, Enum):
    TRANSIENT = "transient"
    NOT_FOUND = "not_found"
    PERMISSION = "permission"
    NO_SPACE = "no_space"
    UNKNOWN = "unknown"

_TRANSIENT = {errno.EAGAIN, errno.EWOULDBLOCK, errno.EINTR,
              errno.ETIMEDOUT, errno.EBUSY}
_NOT_FOUND = {errno.ENOENT, errno.ENOTDIR}
_PERMISSION = {errno.EACCES, errno.EPERM}

def classify(e: OSError) -> Semantic:
    code = e.errno
    if code in _TRANSIENT:
        return Semantic.TRANSIENT
    if code in _NOT_FOUND:
        return Semantic.NOT_FOUND
    if code in _PERMISSION:
        return Semantic.PERMISSION
    if code == errno.ENOSPC:
        return Semantic.NO_SPACE
    return Semantic.UNKNOWN

T = TypeVar("T")

@dataclass
class RetryPolicy:
    max_attempts: int = 3
    base_delay: float = 0.05
    max_delay: float = 1.0
    retryable: set[Semantic] = field(
        default_factory=lambda: {Semantic.TRANSIENT}
    )

    def run(self, fn: Callable[[], T], *, op: str = "unknown") -> T:
        last: OSError | None = None
        for attempt in range(1, self.max_attempts + 1):
            try:
                return fn()
            except OSError as e:
                sem = classify(e)
                last = e
                if sem not in self.retryable:
                    logger.warning("op=%s sem=%s 不可重试", op, sem.value)
                    raise
                delay = min(self.base_delay * (2 ** (attempt - 1)),
                            self.max_delay)
                logger.info("op=%s sem=%s attempt=%d delay=%.3f",
                            op, sem.value, attempt, delay)
                time.sleep(delay)
        assert last is not None
        raise last

6.3 熔断器:unknown 错误的最后防线

# breaker.py
import time
from dataclasses import dataclass

@dataclass
class CircuitBreaker:
    threshold: int = 5
    cooldown: float = 10.0
    _failures: int = 0
    _opened_at: float = 0.0

    @property
    def is_open(self) -> bool:
        if self._failures < self.threshold:
            return False
        if time.monotonic() - self._opened_at > self.cooldown:
            self._failures = 0
            return False
        return True

    def record(self, ok: bool) -> None:
        if ok:
            self._failures = 0
        else:
            self._failures += 1
            if self._failures == self.threshold:
                self._opened_at = time.monotonic()

6.4 Embedding 检索层:把错误码变成可检索知识

这是本框架的"AI 思想"落点之一。我们把历史故障案例向量化,让 Agent 在遇到新错误时能检索相似案例:

# memory.py
from __future__ import annotations
import math
from dataclasses import dataclass

@dataclass
class Case:
    errno_name: str
    semantic: str
    symptom: str
    fix: str

def _toy_embed(text: str, dim: int = 64) -> list[float]:
    """极简哈希 embedding,仅用于演示;生产请替换为真实模型。"""
    vec = [0.0] * dim
    for i, ch in enumerate(text):
        vec[(ord(ch) + i) % dim] += 1.0
    norm = math.sqrt(sum(v * v for v in vec)) or 1.0
    return [v / norm for v in vec]

def cosine(a: list[float], b: list[float]) -> float:
    return sum(x * y for x, y in zip(a, b))

class CaseMemory:
    def __init__(self, cases: list[Case]):
        self.cases = cases
        self._vecs = [_toy_embed(c.symptom + c.fix) for c in cases]

    def search(self, query: str, top_k: int = 2) -> list[tuple[Case, float]]:
        q = _toy_embed(query)
        scored = [(c, cosine(q, v)) for c, v in zip(self.cases, self._vecs)]
        scored.sort(key=lambda x: x[1], reverse=True)
        return scored[:top_k]

6.5 Copilot 决策层:基于检索结果生成处置建议

# copilot.py
from __future__ import annotations
from errno_layer import Semantic, classify
from memory import CaseMemory

class Copilot:
    def __init__(self, memory: CaseMemory):
        self.memory = memory

    def advise(self, e: OSError) -> dict:
        sem = classify(e)
        name = type(e).__name__
        query = f"{name} {e.strerror} {sem.value}"
        hits = self.memory.search(query, top_k=1)
        case, score = hits[0] if hits else (None, 0.0)
        return {
            "semantic": sem.value,
            "errno": e.errno,
            "suggestion": case.fix if case else "无匹配案例,建议人工介入",
            "confidence": round(score, 3),
            "auto_retry": sem == Semantic.TRANSIENT,
        }

6.6 Agent 主循环:把三层串起来

# agent.py
from __future__ import annotations
import logging
from errno_layer import RetryPolicy, Semantic, classify
from breaker import CircuitBreaker
from copilot import Copilot
from memory import Case, CaseMemory

logging.basicConfig(level=logging.INFO,
                    format="%(levelname)s %(name)s %(message)s")

CASES = [
    Case("ENOENT", "not_found", "配置文件缺失 启动失败",
         "检查挂载卷,使用默认配置兜底"),
    Case("EAGAIN", "transient", "非阻塞读取未就绪 传感器超时",
         "指数退避重试,检查连接池大小"),
    Case("ENOSPC", "no_space", "磁盘写满 日志写入失败",
         "清理旧日志,开启日志轮转"),
    Case("EACCES", "permission", "权限不足 无法访问设备节点",
         "检查 udev 规则与运行用户组"),
]

class RobotAgent:
    def __init__(self) -> None:
        self.retry = RetryPolicy(max_attempts=3)
        self.breaker = CircuitBreaker(threshold=3, cooldown=5.0)
        self.copilot = Copilot(CaseMemory(CASES))

    def execute(self, op: str, fn) -> dict:
        if self.breaker.is_open:
            return {"status": "blocked", "reason": "circuit_open"}
        try:
            result = self.retry.run(fn, op=op)
            self.breaker.record(True)
            return {"status": "ok", "result": result}
        except OSError as e:
            self.breaker.record(False)
            advice = self.copilot.advise(e)
            return {"status": "failed", "advice": advice}

6.7 Harness:故障注入与回归断言

harness 是让上述框架"可信"的关键。我们通过注入伪造的 OSError 来验证策略:

# harness.py
from __future__ import annotations
import errno
from agent import RobotAgent

def make_failing(code: int, times: int):
    """构造一个前 times 次失败、之后成功的函数。"""
    state = {"n": 0}
    def fn():
        state["n"] += 1
        if state["n"] <= times:
            raise OSError(code, errno.errorcode.get(code, "?"))
        return "sensor-data"
    return fn

def run_suite() -> None:
    agent = RobotAgent()

    # 用例 1:EAGAIN 两次后成功 -> 应重试成功
    r1 = agent.execute("read_sensor", make_failing(errno.EAGAIN, 2))
    assert r1["status"] == "ok", r1
    print("case1 ok:", r1)

    # 用例 2:ENOENT 不可重试 -> 直接失败并给出建议
    r2 = agent.execute("load_cfg", make_failing(errno.ENOENT, 1))
    assert r2["status"] == "failed"
    assert r2["advice"]["semantic"] == "not_found"
    print("case2 ok:", r2["advice"])

    # 用例 3:连续失败触发熔断
    for _ in range(3):
        agent.execute("flaky", make_failing(errno.EIO, 1))
    r3 = agent.execute("flaky", make_failing(errno.EIO, 1))
    assert r3["status"] == "blocked", r3
    print("case3 ok:", r3)

if __name__ == "__main__":
    run_suite()

运行 python harness.py,预期输出:

INFO robot.errno op=read_sensor sem=transient attempt=1 delay=0.050
INFO robot.errno op=read_sensor sem=transient attempt=2 delay=0.100
case1 ok: {'status': 'ok', 'result': 'sensor-data'}
WARNING robot.errno op=load_cfg sem=not_found 不可重试
case2 ok: {'semantic': 'not_found', 'errno': 2, 'suggestion': '检查挂载卷,使用默认配置兜底', 'confidence': 0.87, 'auto_retry': False}
case3 ok: {'status': 'blocked', 'reason': 'circuit_open'}

(confidence 数值因哈希 embedding 实现而异,断言中未做精确匹配。)

6.8 错误码直方图:把 harness 变成健康度看板

# metrics.py
from collections import Counter
import errno

class ErrnoHistogram:
    def __init__(self) -> None:
        self._c: Counter[str] = Counter()

    def record(self, e: OSError) -> None:
        self._c[errno.errorcode.get(e.errno, "UNKNOWN")] += 1

    def snapshot(self) -> dict[str, int]:
        return dict(self._c.most_common())

    def assert_no_leak(self) -> None:
        """EMFILE 出现即视为 fd 泄漏,回归测试应失败。"""
        if self._c.get("EMFILE", 0) > 0:
            raise AssertionError("检测到 EMFILE,疑似文件描述符泄漏")

在 CI 中,把 assert_no_leak() 挂到 harness 的 teardown,就能把"错误码分布"变成可执行的回归约束。

7. 亮点三:AI 思想与 errno 的融合

7.1 Agent 的"错误直觉"来自错误码先验

人类工程师看到 ENOSPC 会立刻想到磁盘,看到 EAGAIN 会想到"再等等"。Agent 要具备同样的直觉,最经济的方式不是训练大模型,而是把 errno 作为先验知识注入:

  • Semantic 枚举就是先验分类;
  • CaseMemory 就是先验案例库;
  • Copilot.advise 就是先验推理。

这三者构成了一个"小而准"的专家系统,成本远低于端到端模型,且完全可解释。

7.2 Copilot 的边界:什么时候不该自动重试

一个成熟的 copilot 必须知道"不做什么"。基于 errno 的决策边界:

语义自动重试自动修复人工介入
transient✅❌连续失败后
not_found❌✅(兜底默认值)兜底失败后
permission❌❌✅ 必须
no_space❌✅(清理旧文件)清理失败后
unknown❌❌✅ 必须

把这张表写进代码,比写进文档更可靠:

AUTO_ACTIONS = {
    "transient": {"retry"},
    "not_found": {"fallback"},
    "permission": set(),
    "no_space": {"cleanup"},
    "unknown": set(),
}

def allowed_actions(semantic: str) -> set[str]:
    return AUTO_ACTIONS.get(semantic, set())

7.3 Harness 的"对抗性"设计

好的 harness 不只是"跑通",而是"主动找茬"。基于 errno 的对抗性测试至少覆盖:

  1. 边界错误码:EMFILE、ENFILE、ENOMEM 这类资源耗尽型;
  2. 瞬时错误:EINTR 高频注入,验证 PEP 475 自动重试是否被绕过;
  3. 平台差异:在 macOS 与 Linux 上分别跑,验证 EWOULDBLOCK 处理;
  4. 错误码伪造:构造 OSError(9999, "fake"),验证 unknown 分支。
def adversarial_cases() -> list[tuple[str, int]]:
    return [
        ("fd_leak", errno.EMFILE),
        ("mem_exhaust", errno.ENOMEM),
        ("interrupt_storm", errno.EINTR),
        ("fake_code", 9999),
    ]

8. 常见陷阱清单

在长期实践中,以下陷阱反复出现,值得逐条核对:

  1. 硬编码数字:if e.errno == 2 在 Windows 上会失效。
  2. 忘记 from e:raise X from e 保留错误链,否则排障时丢失 errno。
  3. 在 except 里做重 IO:可能再次触发同类错误,形成雪崩。
  4. 把 EAGAIN 当 EINTR:前者需要退避,后者应立即重试。
  5. 忽略 filename 属性:日志里只有 strerror 无法定位是哪个文件。
  6. except Exception 吞掉 OSError:导致熔断器永远不触发。
  7. 跨平台测试缺失:EWOULDBLOCK 与 EAGAIN 在部分平台不同值。
  8. 未处理 ENOSPC:日志写满磁盘后,错误处理本身也失败。

9. 性能与工程权衡

9.1 异常开销

Python 的异常在"不抛出"时几乎零成本(3.11 起 zero-cost exception),但抛出时涉及栈展开,成本约为普通函数调用的数十倍。因此:

  • 高频路径(如每帧传感器读取)应优先用返回值而非异常;
  • 低频路径(如配置加载)用异常更清晰;
  • 重试策略的 base_delay 不宜过小,否则退避本身成为瓶颈。

9.2 语义归一化的成本

classify 函数是纯集合查找,O(1),可放心放在热路径。但 CaseMemory.search 涉及向量计算,应做缓存:

from functools import lru_cache

@lru_cache(maxsize=256)
def cached_advice(errno_code: int, strerror: str) -> str:
    ...

9.3 可观测性开销

结构化日志的 JSON 序列化有成本。建议:

  • 采样:高频错误码按 1/100 采样;
  • 聚合:用 ErrnoHistogram 在进程内聚合,定期 flush;
  • 分级:transient 用 INFO,unknown 用 ERROR。

10. 总结与展望

本报告从 errno 这个"最小的系统接口"出发,走完了从 C 到 Python、从异常到语义、从语义到 Agent 的完整链路。核心结论有三条:

  1. errno 是跨语言、跨平台的错误语义基石。理解它的三条约定(失败才设置、立即读取、TLS 隔离),才能正确使用 Python 的 OSError 体系。
  2. PEP 3151 让错误码"类型化",优先捕获具体子类;需要细分时再判断 errno,并始终用常量而非数字。
  3. 把 errno 注入 Agent 是性价比极高的可靠性工程。Semantic 分类 + CaseMemory 检索 + Copilot 决策 + Harness 对抗测试,构成一个可解释、可回归、可观测的闭环。

展望未来,随着 ExceptionGroup、add_note、结构化日志的普及,errno 的价值会从"错误判断"升级为"错误知识"。当 Agent 能够把每一次 ENOSPC 都转化为一条可检索的经验,机器人系统的可靠性就不再依赖个别工程师的记忆,而是沉淀为可复用的工程资产。

附录 A:errno 速查表(常用 20 个)

常量Linux 值语义Python 异常子类
EPERM1操作不允许PermissionError
ENOENT2文件不存在FileNotFoundError
EINTR4系统调用被中断InterruptedError
EIO5IO 错误OSError
EAGAIN11资源暂不可用BlockingIOError
ENOMEM12内存不足MemoryError(部分场景)
EACCES13权限不足PermissionError
EBUSY16设备忙OSError
EEXIST17文件已存在FileExistsError
ENOTDIR20非目录NotADirectoryError
EISDIR21是目录IsADirectoryError
EINVAL22参数无效OSError
EMFILE24进程 fd 耗尽OSError
ENOSPC28磁盘满OSError
EPIPE32管道破裂BrokenPipeError
ETIMEDOUT110超时TimeoutError
ECONNREFUSED111连接拒绝ConnectionRefusedError
ECONNRESET104连接重置ConnectionResetError
EHOSTUNREACH113主机不可达OSError
EWOULDBLOCK11同 EAGAINBlockingIOError

注:数值以 Linux x86-64 为准,其他平台请以 errno.errorcode 运行时查询为准。

附录 B:完整工程目录结构

robot-agent/
├── errno_layer.py     # 语义分类 + 重试策略
├── breaker.py         # 熔断器
├── memory.py          # embedding 案例检索
├── copilot.py         # 决策建议
├── agent.py           # Agent 主循环
├── harness.py         # 故障注入与回归
├── metrics.py         # 错误码直方图
└── tests/
    └── test_harness.py

附录 C:一键运行脚本

# 依赖:仅标准库,Python 3.11+
python harness.py

若需接入真实 embedding 模型,只需替换 memory._toy_embed,其余接口保持不变——这正是"错误语义层"抽象带来的好处。
在这里插入图片描述

Logo

DAMO开发者矩阵,由阿里巴巴达摩院和中国互联网协会联合发起,致力于探讨最前沿的技术趋势与应用成果,搭建高质量的交流与分享平台,推动技术创新与产业应用链接,围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐