deepseek-harness/packages/e2b/fs-e2b/README.zh.md

@deepseek-ai/dsh-fs-e2b

English | 中文

@deepseek-ai/dsh-fs 提供方 seam 的 E2B 实现。它没有配置：先加载 @deepseek-ai/dsh-e2b，再用本服务取代 dsh-fs-local。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。

行为

• 远程身份与元数据：相对路径以调用方 cwd 或 ctx.e2b.cwd 为基准，按照 POSIX 路径解析；realpath -m 提供规范化目标身份，且不要求最终文件存在。stat、不跟随链接的 lstat 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
• 执行世界路径：规范化目标公开绝对 POSIX 进程路径、百分号编码的 file: URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
• UTF-8 读取：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
• 稳定的有界读取：一个零依赖 Node 辅助程序会以不跟随链接的方式逐级打开目录描述符，并通过一个持续持有的常规文件描述符读取至字节上限。因此，通用 LSP 查询会在服务器启动前拒绝父目录交换、非文件、无效 UTF-8，以及增长后超出所配置文档上限的文件。
• 原子变更：写入会上传 mode 为 0600 的同级临时文件，保留现有文件的 POSIX mode，并通过 E2B 的同目录原子重命名发布。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
• 失败与取消：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 FsError 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。

该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 cwd，只会在远程创建一个拼写相同的目录。

模型体验

通过 dsh-tool-fs 间接影响模型；该工具会渲染远程 UTF-8 内容、目录结果、变更确认和提供方错误，而 E2B 身份及传输保持内部实现。

KV Cache 影响

不会直接失效；请求前缀变更由具名消费方负责。

已知限制与延后工作

• 不提供宿主同步：空的 E2B cwd 会一直为空，直到工具、命令、模板或外部进程填充它；本地文件既不会上传，也不会同步回本地。
• 变更协调仅限宿主进程内：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
• 仍需承担完整文件变更成本：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
• 自定义模板必须支持所用的 Linux、Node、procfs 与 envd 功能：必须支持 realpath、chmod、mv、同一文件系统内的 POSIX rename、流式读取、文件元数据扩展属性、/proc/self/fd 和不跟随链接的描述符打开操作；不支持的模板会失败，而不会静默降级。