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

description, kind

description	kind
文件系统包组：`ctx.fs` 提供方约定、本地与沙箱强制后端、编辑前读取策略插件，以及面向模型的文件与搜索工具。	package-group

packages/fs

English | 中文

概述

fs/ 组为 agent（智能体）提供持久、受策略约束的文件访问：fs/ 定义 ctx.fs 服务约定，fs-local/ 与 fs-sandbox/ 提供宿主文件系统与沙箱强制后端，fs-observation-policy/ 提供编辑前读取策略，tool-fs/（read、read_image、write、edit）与 tool-fs-search/（glob、grep）提供面向模型的工具。部署挂载一个后端，加载策略以获得新鲜度防护的变更，并注册模型应看到的工具包；后端可以更换，无需改动工具或策略。文件 I/O 有意不设超时：deadline 只会杀掉操作系统仍会完成的工作，因此取消只是系统调用边界的尽力而为信号。

目录

• 包
• 相关文档
• 开发备注

---

包

七个包加上远程同级 fs-e2b 承担文件系统角色；子系统参考文档拥有穷尽式约定与错误分类体系。

包	职责	ctx 键
fs/	ctx.fs 服务约定：执行世界路径、有界文本 I/O，以及带可选版本防护的原子变更	ctx.fs
fs-local/	宿主文件系统后端：读取、写入并编辑本机上的真实文件	注册到 ctx.fs
fs-sandbox/	沙箱强制后端：按每次调用的沙箱模式约束写入与编辑，读取直接通过	注册到 ctx.fs
e2b/fs-e2b	以 E2B 为后端：文件状态位于与 E2B 子进程提供方共享的远程执行世界	注册到 ctx.fs
fs-observation-policy/	编辑前读取策略：记录观测到的存在或缺失，并通过 fs/* 事件防护写入/编辑	fs/* 监听器
tool-fs/	面向模型的 read、read_image、write 与 edit 工具及其执行器	注册到 ctx.tools
tool-fs-search/	由打包 ripgrep 二进制支持的面向模型 glob 与 grep 发现工具	注册到 ctx.tools
tool-str-replace-editor/	独立的 str_replace_editor 工具：基于 ctx.fs 的 view、create、str_replace 与 insert	注册到 ctx.tools

策略是插件，不是工具注入的服务：移除它只会让工具回到裸提供方的无条件变更行为，而不会破坏工具。fs-sandbox 的模式围栏与编辑前读取门禁可以组合。tool-fs-search 有意不扩展提供方约定——搜索是由进程支持的 ripgrep 工作流，因此文件系统后端无需承担通用搜索 API。

---

相关文档

先从子系统参考文档了解共享词汇与错误分类体系，再看塑造该家族的设计决策。

• 文件系统子系统——目标、结果、防护、策略事件与错误分类体系。
• 跨能力族 fs 沙箱决策——文件系统 seam 上共享的沙箱模式围栏。
• 可移植执行世界消费方决策——E2B 后端为何共享远程执行世界。

开发备注

维护者的工作上下文——点击展开

无。