README.zh.md 8.2 KB
description: "共享远程沙箱内的文件操作：agent（智能体）可以在那里对文件做什么、何时使用，以及可以期待什么——面向 E2B 家族的部署方与维护者。"
kind: "package-reference"
@deepseek-ai/dsh-fs-e2b
English | 中文
概述
dsh-fs-e2b 让 agent 的文件操作在远程沙箱内运行：agent 可以读取文件、列出目录、写入新文件、覆盖或编辑现有文件，并获得准确的元数据——这些操作都发生在其命令运行的同一远程环境中。它不需要任何配置；挂载它就把文件工作从宿主机器上移走。请与 dsh-e2b、dsh-subprocess-e2b 一起使用，让文件与命令共享同一个远程工作目录。宿主机器上的文件永远不会被触及，模型看到的结果与本地文件结果完全一致。当文件应留在宿主上时，请选择本地的文件系统包。
目录
使用本包
当 agent 的文件工作——读取、写入、编辑、列出——应在远程沙箱内而非你的机器上进行时，使用本包。它是 E2B 家族中的文件系统部分：agent 在这里写入的内容，正是它的命令能在同一个沙箱中读取的内容。
何时选择
当组合已经使用 E2B 沙箱且希望文件操作在其中运行时，选择本包。当文件应留在宿主上时，选择本地文件系统包。这里没有需要调优的配置。
挂载
先加载沙箱所有者，再加载本包；之后文件功能就会作用于沙箱：
- name: '@deepseek-ai/dsh-e2b'
- name: '@deepseek-ai/dsh-fs-e2b'
挂载它不会复制或镜像你的本地文件——沙箱的工作目录从空开始，并随 agent 的工作逐渐被填充。
读取文件
agent 可以读取文件的完整内容、流式读取大文件，或在大小上限内或按字节窗口读取原始字节。二进制文件与不是有效 UTF-8 文本的文件会被明确拒绝而不是乱码显示；超过大小上限的读取会以指明上限的消息失败。
写入与编辑文件
agent 可以创建文件、覆盖文件，或通过替换一段字面量文本（可选地替换所有出现处）来编辑文件，也可以要求仅在文件尚不存在时创建它。一次写入要么完整落地，要么完全不落地——失败的写入绝不会留下不完整的文件。如果文件在 agent 上次读取之后发生了变化，写入会被拒绝而不是覆盖较新的内容，因此两个进程不会在互不知情的情况下覆盖彼此的工作。
沙箱中的路径
相对路径会针对调用方的工作目录或沙箱共享工作目录解析，并按其在沙箱中的 POSIX 路径报告——agent 读写的内容与它的命令看到的内容完全一致。
理解实现
实现细节——点击展开
本节解释提供方背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。 ### 设计理念 - **同一远程环境。** 路径与内容都留在沙箱内；宿主工作区永远不会被复制、挂载或协调。 - **原子发布。** 每次变更都通过同一文件系统 rename 或受防护链接提交，返回的版本来自已提交条目，因此提交点之后不会再有可能失败的元数据请求。 - **严格的传输分帧。** 规范化路径与内容以带 NUL 分帧的 ASCII base64 形式跨越 SDK，因此换行与多字节数据能经受任意解码边界。 ### 源码地图 | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | 插件入口：`E2BFileSystem` 提供方、规范化、读取、原子写入、错误映射 | | — | 不发布运行时不变式配套项；每个操作都直接返回 E2B 控制器的已提交结果，没有可用于交叉核验的独立事件或缓存。 | ### 规范化路径与传输分帧 相对路径以调用方 `cwd` 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 与稳定的单层目录列表会把 E2B 元数据投影到 seam；规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查。 ### 写入路径 写入会创建随机的同级暂存目录，在上传内容前将其 mode 设为 `0700`，并保留现有文件的 POSIX mode；替换操作通过 E2B 的同一文件系统原子重命名发布，带防护的 `createIfAbsent` 改用 `ln -T` 发布，即使目标位置出现目录，也能使提交具备原子且不替换的语义。`dsh-version` 扩展属性与已提交条目的元数据共同构成返回的版本；字面量编辑匹配时会规范化为 LF，并恢复占主导的 CRLF 风格，变更按规范化目标串行执行。提交后的暂存清理失败绝不会把一次成功的写入变成失败。 ### 失败与取消 E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 错误码（`FS_NOT_FOUND`、`FS_PERMISSION_DENIED`、`FS_ABORTED`、`FS_IO_ERROR`），文本与字节读取则增加 `FS_NOT_TEXT` 与 `FS_TOO_LARGE`。取消在 SDK 请求边界与发布前立即检查，但信号永远不会传入 rename 或受防护链接提交，因此取消无法中断原子发布，也不会把已提交的写入报告为失败。进一步探索
当包级约定不够用时阅读以下页面。这些页面从家族组合讲起，逐步深入到文件系统 seam 接口及其渲染工具。
- E2B 提供方家族地图——沙箱所有者与三包组合。
- 文件系统子系统——文件系统 seam 约定与生成的 Cordis 接口。
- 文件系统提供方约定——本提供方实现的
FileSystem接口。 - 文件工具——向模型渲染文件系统结果的工具。
模型体验
通过 dsh-tool-fs 间接影响模型；该工具渲染远程 UTF-8 内容、目录结果、变更确认与提供方错误，而 E2B 身份与传输保持内部实现。
KV Cache 影响
不会直接失效：请求前缀变更由 dsh-tool-fs 负责；E2B 传输永远不会进入请求。
已知限制与延期工作
这些限制说明本提供方何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是待办事项清单。
- 不提供宿主同步：空的 E2B cwd 会一直为空，直到工具、命令或外部进程填充它；本地文件既不会上传，也不会同步回本地。
- 变更协调仅限宿主进程内：
createIfAbsent会保留与发布发生竞态的远程创建者所写入的文件，但另一个 harness 连接或命令仍可能与替换操作发生竞态；版本防护只能检测 E2B 元数据所体现的变更。 - 读取会按路径重新打开规范化目标：在解析与打开流之间若并发替换远程路径，该操作没有稳定文件句柄提供围栏；在该 POC 中，没有已观察到的产品缺陷能够证明提供方专用的有界读取协议值得引入。
- 仍需承担完整文件变更成本：覆盖差异与字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
- 该 POC 面向 E2B 默认 Linux 镜像：它依赖 GNU
realpath／base64／chmod、同一文件系统内的 rename、流式读取与元数据扩展属性；自定义模板不在该 POC 范围内。