errno 深度实践报告:从 C 错误码到 Python 异常体系,再到机器人 Agent 的容错工程
1. 引言:为什么 2026 年还要认真研究 errno
在 Python 生态里,errno 是一个"存在感极低、重要性极高"的模块。它只有几十行代码,导出的常量却支撑着整个 CPython 解释器与操作系统之间的错误传递机制。绝大多数开发者第一次接触它,是在一段 try/except OSError as e: if e.errno == errno.EEXIST: 的代码里;而真正理解它的人,往往是在生产环境被 EINTR、EAGAIN、ENOSPC 这些"幽灵错误"折磨过之后。
本报告以 errno 为切入点,做三件事:
- 解析:从 POSIX 与 Linux 内核的错误码约定出发,讲清
errno在 C 层、CPython 层、Python 应用层的三次"语义跃迁"。 - 亮点:梳理 Python 3.3+ 以来
OSError体系的重构(PEP 3151)、errno与ExceptionGroup、add_note的现代组合用法,以及跨平台差异的工程化处理。 - 复杂工程:把
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() 失败时,错误信息经历了这样的旅程:
在 Python 3.3 之前,这里会分裂成 IOError、OSError、WindowsError、socket.error 等多个类型,判断起来极其痛苦。PEP 3151 之后,它们统一为 OSError,并引入了按 errno 自动派生的子类。
3.2 PEP 3151:错误码到异常类的映射表
CPython 内部维护了一张映射表,把常见 errno 映射到更具体的异常子类:
| errno | 异常子类 | 典型场景 |
|---|---|---|
ENOENT | FileNotFoundError | 文件不存在 |
EEXIST | FileExistsError | 文件已存在 |
EACCES / EPERM | PermissionError | 权限不足 |
EISDIR | IsADirectoryError | 对目录做文件操作 |
ENOTDIR | NotADirectoryError | 对文件做目录操作 |
EINTR | InterruptedError | 系统调用被信号打断 |
ETIMEDOUT | TimeoutError | 超时 |
ECONNREFUSED | ConnectionRefusedError | 连接被拒绝 |
EAGAIN | BlockingIOError | 非阻塞 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 整体架构
设计要点:
- 错误语义层是唯一入口:所有
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 的对抗性测试至少覆盖:
- 边界错误码:
EMFILE、ENFILE、ENOMEM这类资源耗尽型; - 瞬时错误:
EINTR高频注入,验证PEP 475自动重试是否被绕过; - 平台差异:在 macOS 与 Linux 上分别跑,验证
EWOULDBLOCK处理; - 错误码伪造:构造
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. 常见陷阱清单
在长期实践中,以下陷阱反复出现,值得逐条核对:
- 硬编码数字:
if e.errno == 2在 Windows 上会失效。 - 忘记
from e:raise X from e保留错误链,否则排障时丢失 errno。 - 在 except 里做重 IO:可能再次触发同类错误,形成雪崩。
- 把
EAGAIN当EINTR:前者需要退避,后者应立即重试。 - 忽略
filename属性:日志里只有strerror无法定位是哪个文件。 except Exception吞掉 OSError:导致熔断器永远不触发。- 跨平台测试缺失:
EWOULDBLOCK与EAGAIN在部分平台不同值。 - 未处理
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 的完整链路。核心结论有三条:
- errno 是跨语言、跨平台的错误语义基石。理解它的三条约定(失败才设置、立即读取、TLS 隔离),才能正确使用 Python 的
OSError体系。 - PEP 3151 让错误码"类型化",优先捕获具体子类;需要细分时再判断
errno,并始终用常量而非数字。 - 把 errno 注入 Agent 是性价比极高的可靠性工程。
Semantic分类 +CaseMemory检索 +Copilot决策 +Harness对抗测试,构成一个可解释、可回归、可观测的闭环。
展望未来,随着 ExceptionGroup、add_note、结构化日志的普及,errno 的价值会从"错误判断"升级为"错误知识"。当 Agent 能够把每一次 ENOSPC 都转化为一条可检索的经验,机器人系统的可靠性就不再依赖个别工程师的记忆,而是沉淀为可复用的工程资产。
附录 A:errno 速查表(常用 20 个)
| 常量 | Linux 值 | 语义 | Python 异常子类 |
|---|---|---|---|
| EPERM | 1 | 操作不允许 | PermissionError |
| ENOENT | 2 | 文件不存在 | FileNotFoundError |
| EINTR | 4 | 系统调用被中断 | InterruptedError |
| EIO | 5 | IO 错误 | OSError |
| EAGAIN | 11 | 资源暂不可用 | BlockingIOError |
| ENOMEM | 12 | 内存不足 | MemoryError(部分场景) |
| EACCES | 13 | 权限不足 | PermissionError |
| EBUSY | 16 | 设备忙 | OSError |
| EEXIST | 17 | 文件已存在 | FileExistsError |
| ENOTDIR | 20 | 非目录 | NotADirectoryError |
| EISDIR | 21 | 是目录 | IsADirectoryError |
| EINVAL | 22 | 参数无效 | OSError |
| EMFILE | 24 | 进程 fd 耗尽 | OSError |
| ENOSPC | 28 | 磁盘满 | OSError |
| EPIPE | 32 | 管道破裂 | BrokenPipeError |
| ETIMEDOUT | 110 | 超时 | TimeoutError |
| ECONNREFUSED | 111 | 连接拒绝 | ConnectionRefusedError |
| ECONNRESET | 104 | 连接重置 | ConnectionResetError |
| EHOSTUNREACH | 113 | 主机不可达 | OSError |
| EWOULDBLOCK | 11 | 同 EAGAIN | BlockingIOError |
注:数值以 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,其余接口保持不变——这正是"错误语义层"抽象带来的好处。

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




所有评论(0)