openai-agents-python 沙箱核心类型体系深度解析：User、Permissions、ExecResult 与 ExposedPortEndpoint 源码级指南

openai-agents-python 沙箱核心类型体系深度解析：User、Permissions、ExecResult 与 ExposedPortEndpoint 源码级指南

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python

agents.sandbox.types是 openai-agents-python 沙箱（Sandbox）子系统最底层的数据类型模块，定义了沙箱中"谁在运行、以什么权限运行、运行结果如何返回、对外端口如何暴露"这四类基础模型。本文以 types.md 对应的 types.py 源码为骨架，逐一拆解每个类型的字段、方法、设计意图与底层实现，并对照unix_local、docker等实际运行时与测试用例，帮助你真正读懂沙箱的运行模型，为自定义 Sandbox 运行时或排查沙箱问题打下基础。

一、模块定位：沙箱世界的“基础类型层”

在 openai-agents-python 中，沙箱（Sandbox）为 Agent 的代码执行提供隔离环境。整个沙箱体系分布在src/agents/sandbox/下，而types.py是其中最基础、被引用面最广的模块——它不依赖任何沙箱实现，只定义纯粹的数据结构。

从 sandbox/init.py 可以看到，该模块向包外公开了六个符号：

from .types import ExecResult, ExposedPortEndpoint, FileMode, Group, Permissions, User

也就是说，任何使用者都可以通过from agents.sandbox import User, Permissions, ...直接导入。而在模块内部，这些类型被大量消费：

• entries/base.py 导入FileMode, Group, Permissions, User，用于描述工作区条目（文件、目录、挂载点）的属主与权限；
• manifest.py 导入Group, User，用于生成沙箱清单；
• sandboxes/unix_local.py 与 sandboxes/docker.py 导入ExecResult, ExposedPortEndpoint, Permissions, User，用于两种实际运行时的执行结果封装与端口映射；
• capabilities/capability.py、apply_patch.py、runtime.py等大量模块导入User，用于表示沙箱内操作的用户身份。

可以这样理解分层：types.py是"词汇表"，entries、manifest、runtime是"语法"，而docker、unix_local是"方言实现"。本文就从这个词汇表讲起。

二、User 与 Group：沙箱内的身份模型

沙箱内的每个文件、进程都归属某个用户，跨文件系统操作时权限判定也依赖用户身份。types.py用两个极简的 Pydantic 模型表达这一概念。

2.1 User：单一身份

class User(BaseModel): name: str def __hash__(self) -> int: return hash(self.name) def __eq__(self, other: object) -> bool: if not isinstance(other, User): return NotImplemented return self.name == other.name

要点：

• 字段只有一个name，即用户名，语义上对应 Unix 用户名（如root、sandbox）。
• 重写了__eq__与__hash__，以 name 作为身份判等与哈希的唯一依据。这意味着两个User(name="root")实例在集合、字典、去重场景中被视为同一个用户。
• 它是 PydanticBaseModel子类，支持User(name="root")这样的构造方式与字段校验。

2.2 Group：用户组

class Group(BaseModel): name: str users: list[User] def __hash__(self) -> int: return hash(self.name) def __eq__(self, other: object) -> bool: if not isinstance(other, Group): return NotImplemented return self.name == other.name

要点：

• 字段name（组名）与users（组成员列表）。
• 同样以name为判等依据，users不参与相等比较——一个组"是什么"由名字决定，成员变化不改变组的身份。
• 从源码结构看，Group 主要用于manifest.py与entries/base.py中表达"组权限"场景：某个文件/目录归属于某个组，组内成员共享group权限位。

2.3 为什么实现__hash__？

Python 中定义了__eq__的类默认会失去可哈希性（__hash__置为None）。这里显式补回__hash__，是为了让User/Group能安全地放进set或作为dict的键——例如沙箱在计算用户去重、权限合并时，可以依赖这一身份语义。这是实现细节，但也是阅读后续沙箱代码时容易踩坑的地方。

三、Permissions：与 Unix 权限位完全对齐的权限模型

Permissions是types.py中实现最丰富、也最值得精读的类。它把 Unix 权限三元组（owner/group/other）与目录标志封装为可双向转换的模型，同时兼容"八进制 mode"与"ls -l 风格字符串"两种表达。

3.1 字段与默认值

class Permissions(BaseModel): owner: int = Field(default=0o7) group: int = Field(default=0) other: int = Field(default=0) directory: bool = Field(default=False)

默认值即"属主完全控制、其余无权限"（0o700），这是沙箱内工作区文件默认权限的合理选择——默认不给组和其他用户任何访问权。注意默认值用八进制字面量0o7，与 FileMode.ALL 常量保持一致（见后文）。

3.2 to_mode()：转换为 Unix mode 整数

def to_mode(self) -> int: mode = 0 for perms, shift in [(self.owner, 6), (self.group, 3), (self.other, 0)]: mode |= int(perms) << shift if self.directory: mode |= stat.S_IFDIR return mode

实现逻辑：owner 左移 6 位（rwx 对应 bit 6~8），group 左移 3 位，other 不移动，三者按位或合并；若是目录则再叠加stat.S_IFDIR文件类型位。结果可直接用于os.chmod、stat比较等场景。

3.3 from_mode()：从 mode 整数反解

@classmethod def from_mode(cls, mode: int) -> "Permissions": return cls( owner=(mode >> 6) & 0b111, group=(mode >> 3) & 0b111, other=(mode >> 0) & 0b111, directory=bool(mode & stat.S_IFDIR), )

与to_mode互逆。在 unix_local.py 中，本地运行时正是用Permissions.from_mode(stat_result.st_mode)把os.stat得到的真实文件 mode 还原为权限对象，用于向沙箱侧描述文件状态。

3.4 from_str()：解析 ls -l 风格字符串

这是兼容性最强的入口，专门处理drwxr-xr-x这类 10 字符（或带后缀的 11 字符）权限串：

@classmethod def from_str(cls, perms: str) -> "Permissions": # coreutils/BSD ls append a single trailing marker to the mode field to flag # alternate access methods: "+" (ACL), "@" (macOS extended attributes), and # "." (SELinux security context). Strip it before parsing the 10 mode chars. if len(perms) == 11 and perms[-1] in {"@", "+", "."}: perms = perms[:-1] if len(perms) != 10: raise ValueError(f"invalid permissions string length: {perms!r}") directory = perms[0] == "d" if perms[0] not in {"d", "-"}: raise ValueError(f"invalid permissions type: {perms!r}") ...

解析规则：

• 首位字符：d表示目录，-表示普通文件，其他字符直接抛ValueError；
• 每三位一组分别解析 owner/group/other 的r（读）、w（写）、执行位；
• 执行位支持特殊字符：属主/属组位置可接受x/s/S（s为带 setuid/setgid 的执行位，S为无执行位的 setuid/setgid），other 位置接受x/t/T（sticky bit 语义）；
• 长度不是 10 时抛错；特别地，会先剥离 coreutils/BSDls附加的 ACL（+）、macOS 扩展属性（@）、SELinux 上下文（.）后缀标记。

这意味着你可以直接把ls -l的输出喂给Permissions.from_str，而无需手动清洗字符串——对解析外部工具输出非常友好。

3.5 链式配置方法

def owner_can(self, mode: int) -> Self: self.owner = mode return self def group_can(self, mode: int) -> Self: self.group = mode return self def others_can(self, mode: int) -> Self: self.other = mode return self

三个方法分别设置属主/属组/其他权限位并返回self，支持链式调用。注意返回类型是Self（typing_extensions），且原地修改后返回自身，适合在构建配置时写出声明式风格，例如：

perms = Permissions().owner_can(FileMode.ALL).group_can(FileMode.READ | FileMode.EXEC)

3.6 字符串表示与判等语义

• __repr__输出形如d rwx r-x ---的 10 字符串（目录标志 + 三组 rwx 展开），__str__复用repr；
• __eq__以to_mode()的结果判等——只要最终 mode 相同，即便内部 owner/group/other 组合不同也视为相等；
• __hash__同样基于to_mode()，保证相等的对象哈希一致。

从源码结构可以推断：以 mode 为判等基准，是为了让"同一个权限状态"在不同表达方式（八进制、字符串、字段组合）下可以互等，便于沙箱状态同步与 diff 检测。

四、FileMode：权限位的枚举常量

class FileMode(IntEnum): ALL = 0o7 NONE = 0 READ = 1 << 2 WRITE = 1 << 1 EXEC = 1

FileMode继承IntEnum，因此可直接与整数位运算混用：

典型用法是位或组合，例如FileMode.READ | FileMode.WRITE表示 rw-。测试代码 tests/sandbox/capabilities/test_skills_capability.py 中的Permissions(owner=FileMode.ALL, group=0, other=0)即用FileMode.ALL表达属主全权。由于是IntEnum，它还能与来自stat模块的 mode 整数直接比较、运算，避免了常量语义漂移。

五、ExecResult：命令执行结果的统一载体

沙箱内执行命令后，所有运行时（Docker、Unix 本地、甚至测试替身）都用同一个ExecResult返回结果，保证上层调用方无需关心后端差异。

class ExecResult: stdout: bytes stderr: bytes exit_code: int def __init__(self, *, stdout: bytes, stderr: bytes, exit_code: int) -> None: self.stdout = stdout self.stderr = stderr self.exit_code = exit_code def ok(self) -> bool: return self.exit_code == 0

要点：

• 三个字段全部为bytes/int：stdout、stderr是原始字节流，exit_code是进程退出码；
• 三个参数均为关键字参数（*强制），调用形如ExecResult(stdout=b"...", stderr=b"", exit_code=0)；
• ok()方法封装"退出码是否为 0"的判断，供上层快速判断成败。

它在代码库中的使用非常普遍，例如 tests/sandbox/_filesystem_test_session.py 用ExecResult(stdout=b"", stderr=b"", exit_code=0 if exists else 1)模拟文件存在性检查；unix_local.py 则把本地子进程的真实输出封装进ExecResult返回。错误场景下，stderr携带错误信息、exit_code非 0，配合 errors.py 中的ExecTimeoutError、ExecTransportError等异常类型构成完整的执行错误模型。

六、ExposedPortEndpoint：沙箱对外端口映射描述

当沙箱需要暴露端口（如启动一个 HTTP 服务供外部访问）时，ExposedPortEndpoint描述"如何访问这个端口"。

@dataclass(frozen=True) class ExposedPortEndpoint: host: str port: int tls: bool = False query: str = "" def url_for(self, scheme: str) -> str: ...

字段一览：

它是frozen=True的 dataclass，创建后不可修改，天然适合作为不可变描述对象。例如 unix_local.py 中本地运行时的实现：

async def _resolve_exposed_port(self, port: int) -> ExposedPortEndpoint: return ExposedPortEndpoint(host="127.0.0.1", port=port, tls=False)

即本地端口直接映射到回环地址。

6.1 url_for()：一键生成访问 URL

def url_for(self, scheme: str) -> str: normalized = scheme.lower() if normalized not in {"http", "ws"}: raise ValueError("scheme must be either 'http' or 'ws'") ...

行为规则：

• 只接受http与ws两种 scheme（大小写不敏感），其余抛ValueError；
• 根据tls自动选择协议前缀：http→https/http，ws→wss/ws，默认端口分别为 443/80；
• 当端口等于默认端口时省略端口号；非默认端口则显式拼接:port；
• IPv6 主机地址自动加方括号（如[::1]）；
• query自动去掉开头的?后拼接到 URL 末尾。

例如ExposedPortEndpoint(host="127.0.0.1", port=8080).url_for("http")得到http://127.0.0.1:8080/；而tls=True且port=443时得到https://127.0.0.1/。这一方法让沙箱调用方无需关心协议与端口细节，直接拿到可访问的 URL。

七、源码级关联：这些类型如何支撑沙箱运转

理解了六个类型之后，把它们放回沙箱运行链路中看，脉络会非常清晰：

1. 身份与权限：User/Group描述"以谁的身份"，Permissions/FileMode描述"能做什么"。它们被 entries/base.py 用于构造工作区条目（Dir、File、各挂载类型），被 manifest.py 用于生成沙箱清单（Manifest）中的属主与权限声明，最终在创建沙箱文件系统时落地为真实的 mode 位。
2. 执行与结果：沙箱运行命令后，sandboxes/unix_local.py 与 sandboxes/docker.py 统一以ExecResult返回 stdout/stderr/exit_code；上层 Capability（如 shell、apply_patch、skills）基于ok()与输出内容决策下一步。
3. 网络暴露：沙箱暴露端口时，运行时通过_resolve_exposed_port返回ExposedPortEndpoint，调用方用url_for生成 HTTP/WebSocket 地址访问沙箱内服务。

对应的参考文档还可继续深入：permissions.md 单独收录了User/Group/Permissions/FileMode四个类型的 API 参考；entries.md 收录工作区条目类型；snapshot.md 收录快照相关模型；完整的沙箱运行配置可参阅 config.md 与 runtime.md。

八、实战速查：常用构造示例

以下示例均基于 types.py 的公开 API，可直接在项目中验证：

from agents.sandbox import ( ExecResult, ExposedPortEndpoint, FileMode, Group, Permissions, User, ) # 1. 身份 alice = User(name="alice") devs = Group(name="devs", users=[alice]) # 2. 权限：属主读写执行，组内可读执行，其他无权限 perms = Permissions(owner=FileMode.ALL, group=FileMode.READ | FileMode.EXEC, other=0) assert perms.to_mode() == 0o750 assert Permissions.from_mode(0o750) == perms assert Permissions.from_str("drwxr-x---") == Permissions( owner=FileMode.ALL, group=FileMode.READ | FileMode.EXEC, other=0, directory=True ) # 3. 链式配置 rw = Permissions().owner_can(FileMode.READ | FileMode.WRITE) # 4. 执行结果 result = ExecResult(stdout=b"hello\n", stderr=b"", exit_code=0) assert result.ok() is True # 5. 端口端点 endpoint = ExposedPortEndpoint(host="127.0.0.1", port=8080) assert endpoint.url_for("http") == "http://127.0.0.1:8080/" tls_endpoint = ExposedPortEndpoint(host="example.com", port=443, tls=True) assert tls_endpoint.url_for("ws") == "wss://example.com/"

九、总结

agents.sandbox.types用六个精炼的类型，把沙箱最底层的四个关注点——身份（User/Group）、权限（Permissions/FileMode）、执行结果（ExecResult）、端口暴露（ExposedPortEndpoint）——完整地模型化。它们既是沙箱各运行时（Docker、Unix 本地）与上层能力（Capability、Manifest、Entries）之间的公共契约，也是阅读整个src/agents/sandbox/代码库的最佳起点。当你需要自定义 Sandbox 运行时或调试沙箱行为时，先吃透这份"词汇表"，往往能事半功倍。

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python