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 路径解析；GNU realpath -mz 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。stat、不跟随链接的 lstat 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
• 执行世界路径：规范化目标公开绝对 POSIX 进程路径、百分号编码的 file: URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
• UTF-8 读取：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
• 原子变更：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 0700，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
• 失败与取消：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 FsError 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。

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

模型体验

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

KV Cache 影响

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

已知限制与延后工作

• 不提供宿主同步：空的 E2B cwd 会一直为空，直到工具、命令或外部进程填充它；本地文件既不会上传，也不会同步回本地。
• 变更协调仅限宿主进程内：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
• 读取会按路径重新打开规范化目标：在解析与打开流之间若并发替换远程路径，该操作没有稳定文件句柄提供围栏；在该 POC 中，没有已观察到的产品缺陷能够证明提供方专用的有界读取协议值得引入。
• 仍需承担完整文件变更成本：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
• 该 POC 面向 E2B 默认 Linux 镜像：它依赖 GNU realpath／base64／chmod、同一文件系统内的 rename、流式读取和元数据扩展属性；自定义模板不在该 POC 范围内。