Filesystem zh

文件系统

上游文件操作子系统在 Edge 中的适配。

上游参考：文件系统

上游提供了什么

文件系统子系统通过四个包为模型提供安全的、有保护的文件操作：

• dsh-fs — 抽象 FileSystem 服务（ctx.fs），定义 resolve、stat、lstat、readText、streamText、writeText、editText、readBytes、listDir。
• dsh-fs-local — 使用 node:fs 的本地磁盘后端。
• dsh-tool-fs — 注册四个模型工具：read、write、edit、read_image。
• dsh-sandbox — 强制可写根目录策略和路径规范化。

写入保护（createIfAbsent、replaceIfVersion）防止过时覆盖。编辑是原子的字面替换，带匹配验证。错误码（FS_STALE_VERSION、FS_NOT_FOUND、FS_IO_ERROR 等）稳定且可编程。

Edge 改了什么

替换件 EdgeFileSystem → Cloudflare Computer VFS

EdgeFileSystem（309 行）继承上游抽象 FileSystem 类。每个方法委托给 Cloudflare Computer VFS API。关键适配：

• AsyncLocalStorage 提供 turn 作用域的 VFS 绑定——每个活跃 turn 通过 runInScope() 获得自己的 {vfs, cwd}，同一 DO 上的并发 session 不会交叉污染。
• readText 在读取后调用 stat 获取真实的 mtime:size 版本令牌，匹配上游的新鲜度保护契约。
• streamText 返回单次 yield 的异步可迭代对象——VFS 没有流式 API，读取全部内容后一次 yield。
• writeText 创建父目录——写入前通过 vfs.mkdir(parentDir, { recursive: true })，因为 VFS 路径可能不存在。
• stat/lstat 对 ENOENT 返回 undefined；其他错误传播为 FS_IO_ERROR。

直接复用 ToolFs

dsh-tool-fs 原封安装。四个模型工具使用 ctx.fs（解析为 EdgeFileSystem）。工具 schema、保护逻辑、diff 输出格式和行号显示都是上游代码。

补丁 dsh-sandbox

Sandbox 补丁移除两个 Node.js 导入：

• node:fs realpathSync → canonicalPath() 直接返回路径（VFS 没有符号链接）。
• node:os tmpdir() → writableRoots 省略 OS 临时目录。

移除条件：上游提供 VFS 兼容的 sandbox 或移除 Node.js 导入。

Edge 没有改什么

• 工具定义和参数 schema（read/write/edit/read_image）
• 写入保护语义（createIfAbsent、replaceIfVersion）
• 编辑原子性和匹配验证
• 错误码及其稳定分类
• 观察策略事件（fs/write-intent、fs/edit-intent、fs/observed）

性能特征

VFS I/O

所有文件操作通过 Cloudflare Computer 的 VFS，这是一个限定在 workspace 容器内的内存文件系统。读写很快（没有传统意义上的磁盘 I/O），但受容器内存分配限制。大文件可能在触及上游 FS_TOO_LARGE 字节上限之前就碰到 VFS 内存限制。

AsyncLocalStorage 开销

AsyncLocalStorage.run() 是 V8 原生实现，每次调用开销极小——远低于 1 微秒。每个 turn 调用一次（在 runInScope() 中），不是每个文件操作都调用。turn 内部的 getStore() 是单次上下文查找。

并发 session 安全性

每个 turn 的 VFS 绑定通过 AsyncLocalStorage 限定作用域，共享同一 DO 的两个 session 可以并发执行文件操作而不交叉污染。此前使用全局 activeBinding 变量，在交错异步 turn 下导致错误 VFS 绑定——在 0.7.0-alpha.1 中替换。

版本令牌准确性

readText 在读取文件后调用 vfs.stat() 获取真实的 mtime:size 对。确保版本令牌匹配实际文件状态，防止后续编辑时出现误报 FS_STALE_VERSION 错误。额外的 stat 调用增加一次 VFS 往返。

架构总结

组件	分类	Edge 代码
EdgeFileSystem	替换	309 行——VFS 委托 + AsyncLocalStorage
ToolFs (read/write/edit/read_image)	复用	一行 ctx.plugin() 调用
dsh-sandbox 补丁	补丁	移除 node:fs + node:os 导入

关键观察：EdgeFileSystem 是教科书式的能力接缝替换——上游定义抽象 FileSystem 类，Edge 提供平台相关后端。工具层和保护逻辑完全运行上游代码。唯一的补丁在 sandbox（Node.js 导入），不在文件系统本身。