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 元数据与每次写入设置的扩展属性所组成的不透明哈希。
• UTF-8 读取：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
• 原子变更：写入会上传 mode 为 0600 的同级临时文件，保留现有文件的 POSIX mode，并通过同目录 Linux mv -f 发布。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
• 失败与取消：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 FsError 词汇。取消在 SDK 请求边界上采用尽力而为语义；成功 rename 是提交点。

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

模型体验

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

KV Cache 影响

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

已知限制与延后工作

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