DeepSeek Harness 从入门到精通

Appearance

3.3 文件系统能力族 ​

本章概览：DSH 的文件系统能力不是"一个读写工具"，而是一条四层栈——提供方契约、本地/沙箱实现、经 fs/* 事件门参与的策略插件、模型侧工具。读完可回答：为什么 edit 要求先 read，为什么用字符串替换而非整文件重写，glob/grep 为什么不走 ctx.fs。

概述 / 定位 ​

fs 能力族位于 packages/fs/ 下，全部是产品包：

包角色ctx 键
dsh-fsService Definition：存储原语 + fs/* 事件词汇ctx.fs
dsh-fs-localProvider：宿主文件系统实现（注册 ctx.fs）
dsh-fs-sandboxProvider：沙箱围栏实现（扩展 fs-local）（注册 ctx.fs）
dsh-fs-observation-policy策略插件：观察状态 + 写前读 + 版本守卫（无服务，仅 fs/* 监听）
dsh-tool-fsConsumer：模型侧 read/write/edit/read_image 与执行器（注册 ctx.tools）
dsh-tool-fs-searchConsumer：模型侧 glob/grep 发现工具（注册 ctx.tools）
dsh-tool-str-replace-editorConsumer：独立 str_replace_editor 工具（注册 ctx.tools）

出处：packages/fs/README.md（deepseek-harness-src/packages/fs/README.md）

它在 agent-loop 主干之外、是可选项：换后端（本地→沙箱→远程 E2B）不触碰策略与工具 schema。搜索有意不扩展提供方契约——glob/grep 是 ripgrep 进程工作流，经 ctx.subprocess 跑打包的 @vscode/ripgrep 二进制，而不是 ctx.fs 的方法。

核心机制 ​

四层栈与三角色 ​

dsh-fs 把"读文件"拆成四个可独立演化的层：tool/executor（dsh-tool-fs）→ policy（dsh-fs-observation-policy）→ provider contract（dsh-fs）→ provider（dsh-fs-local / dsh-fs-sandbox / E2B）。关键在 policy 层：它不是工具注入的服务，而是一个只通过 fs/* 事件门参与的插件——删掉它，工具优雅回落到裸 provider（无条件写/编辑），不会在服务注入边界上断裂。

出处：packages/fs/fs/README.md（deepseek-harness-src/packages/fs/fs/README.md）

ctx.fs 契约要点 ​

FileSystem 实现十二个原语：resolve / processPath / fileUrl / contains / stat / lstat / readText / streamText / readBytes / listDir / writeText / editText。要点：

  • 目标身份：resolve(path) 产出不透明的 FsTarget（targetKey 是品牌化不透明 id，消费方不得解析；只有 displayPath 可展示）。processPath / fileUrl 提供"执行世界"坐标，contains 测规范包含关系。
  • 原子突变：writeText / editText 都是原子写（临时文件 + fsync + 发布），版本守卫可选——省略即无条件，提供即守卫。守卫是 FsWriteIntent：createIfAbsent（缺失才创建，存在报 FS_NOT_OBSERVED）或 replaceIfVersion（仅在观察版本上替换，否则 FS_STALE_VERSION）。
  • 结构化错误码：FsErrorCode 闭集（FS_NOT_FOUND、FS_STALE_VERSION、FS_NOT_OBSERVED、FS_SANDBOX_DENIED、FS_AMBIGUOUS_EDIT、FS_EDIT_NOT_FOUND 等），工具注册表在 isError 结果上暴露 { name, code }。

fs-sandbox：写围栏 ​

SandboxedFileSystem 继承本地实现全部机制，只对 writeText / editText 加逐调用模式围栏：read-only 一律拒绝（结构化 FS_SANDBOX_DENIED，携带生效模式）；workspace-write 只允许目标落在 workspace 根与平台临时区之下；danger-full-access 不围栏。读永远放行。它与 bash 共享同一个 ctx.sandboxPolicy 解析出的 per-call policy（mode + 会话 cwd 根），可写根集合来自单一来源函数 writableRoots——fs 围栏与 bash runner 不可能漂移。拒绝是进程内精确的结构化错误，无需像 bash 那样从 stderr 推断。

出处：packages/fs/fs-sandbox/README.md（deepseek-harness-src/packages/fs/fs-sandbox/README.md）

观察策略：fs/* 事件门 ​

dsh-fs-observation-policy 注册三个 fs/* 事件监听（事件词汇归 dsh-fs 所有，发方是 dsh-tool-fs，监听方是策略插件——发方不依赖策略包）：

事件类型策略插件的处理
fs/write-intent单槽决策 waterfall未见过/确认缺席 → createIfAbsent；观察到 present → replaceIfVersion（带观察版本）
fs/edit-intent单槽决策 waterfall未见过 → FS_NOT_OBSERVED；确认缺席 → FS_NOT_FOUND；present → 以观察版本作 CAS 基准
fs/observed即发即忘记录同步、仅副作用的 WeakMap.set，记录 present(version) 或 absent

两个 intent 槽是单槽、注册顺序首胜：策略插件完全决策、不调用 next()。观察状态是"先验记录"（unseen / absent / present@version），策略插件本身不做任何文件系统 I/O——它把状态转换成 provider 的守卫。移除插件后工具回落到裸 provider；这正是事件门相对强制方法服务的全部意义。

出处：packages/fs/fs-observation-policy/README.md（deepseek-harness-src/packages/fs/fs-observation-policy/README.md）

模型侧工具集 ​

工具参数行为
readfile_path, offset?, limit?带行号的 UTF-8 内容 + 分页 footer；offset 从 1 起，limit 默认并封顶 2000
read_imagefile_path仅在有持久 attachment 服务且路由模型声明 image 输入时注册/执行
writefile_path, content创建或整体替换；策略下覆盖已有文件需先 read 且版本未变
editfile_path, old_string, new_string, replace_all?字面替换；默认要求唯一匹配
globpattern, path?rg --files 发现文件，--no-config 防 RIPGREP_CONFIG_PATH 注入
greppattern, path?, include?rg --json 行式匹配，按文件分组
str_replace_editorview/create/str_replace/insert绝对路径编辑器命令集

工具侧还注册了固定提示词段：读用 read 而非 cat（"Results include line numbers. Use offset and limit to continue reading large files."）、写用 write（"Existing files are overwritten, so read an existing file first..."）、编辑用 edit（"Use the edit tool for targeted changes to existing UTF-8 text files..."）。

出处：packages/fs/tool-fs/README.md 与 packages/fs/tool-fs-search/README.md（均在 deepseek-harness-src/packages/fs/ 下）

为什么字符串替换而非整文件重写 ​

edit / str_replace_editor 坚持"字面字符串替换"而不是"模型重发整个文件"：

  1. token 与噪声：整文件重写要模型重新产生全部内容，代价高且容易夹带与目标无关的改动；字面替换只传一小段 old_string，且 old_string 必须唯一匹配（多匹配默认报 FS_AMBIGUOUS_EDIT，除非 replace_all）。
  2. 编辑是提供方原语，不是 read+write 组合：版本守卫校验、字面匹配、原子重写必须留在一个临界区内，才能正确归因错误（陈旧先报 FS_STALE_VERSION，而不是对新内容报匹配失败）并保证"一胜一败"的并发语义；远程后端还可实现为原生 compare-and-edit。
  3. 展示即输入：str_replace_editor 的 view 用 1 起行号并保留内容 tab，使展示文本可直接当作字面替换输入；str_replace 拒绝 0/多匹配且没有 replace_all 参数，从契约上逼模型给出精确的唯一片段。

出处：packages/fs/tool-str-replace-editor/README.md（deepseek-harness-src/packages/fs/tool-str-replace-editor/README.md）与 docs/subsystems/filesystem.md（deepseek-harness-src/docs/subsystems/filesystem.md）

"写前观察"模式 ​

默认部署的完整工作流是：先 read（记录版本）→ 再 write/edit（带版本守卫）。策略把守卫翻译成可操作的错误与恢复指令：

  • 未先读就 edit：FS_NOT_OBSERVED，精确文案 edit requires reading "<path>" first；
  • 版本已变：FS_STALE_VERSION，工具层追加恢复指令 — re-read the file, then retry；
  • 观察到缺席：只允许 createIfAbsent 写，edit 报 FS_NOT_FOUND。

观察状态是进程内 WeakMap、不跨会话持久化：恢复的会话必须先重读。授权语义是"版本新鲜度"而非"视图完整性"——任何窗口的 read 只要文件未变就授权后续整文件覆盖，这是刻意比"完整视图"更弱的规则。

无超时 ​

read/write/edit 没有 timeoutMs，契约也不挂截止时间：文件 IO 是尽力可中止的本地 syscall，截止时间杀不掉正在进行的 fsync/rename；取消经工具执行信号在 syscall 边界尽力传播。这与进程托底的 bash/web（有超时）形成对照。

出处：packages/fs/README.md（deepseek-harness-src/packages/fs/README.md）

关键设计决策 ​

  • 策略走事件门而非方法服务：fs/write-intent/fs/edit-intent 单槽决策 + fs/observed 即发即忘，发方与策略解耦，策略可优雅装卸。
  • 守卫可选，裸 provider 是完整缝：ctx.fs 自身是无约束的完整存储缝；观察策略是"策略插件加上的策略"，不是提供方行为——沙箱/远程后端不会继承模型面向的观察策略。
  • 编辑留在缝上：版本 + 字面匹配 + 原子重写在一个临界区，错误归因与并发语义才正确。
  • 文本优先契约：UTF-8 解码、二进制拒绝（FS_NOT_TEXT）在缝上完成，策略层永不触碰原始字节；readBytes 是唯一裸字节原语。
  • 搜索独立于 fs 缝：不强迫每个文件系统后端实现搜索 API；ripgrep 进程工作流自带平台二进制、固定 argv（--no-config）与结构化错误码。
  • 无超时：不给契约无法执行的截止时间承诺。

扩展点 ​

  • 新后端：实现 FileSystem 十二原语注册 ctx.fs（如 E2B 远程实现）；沙箱/远程后端自动继承策略与工具层。
  • 新策略：注册 fs/write-intent / fs/edit-intent 决策监听（单槽，注册顺序决定胜者）；注意这不是可组合授权链，分层权限/审计拦截应走 tools/execute。
  • 新工具：在 dsh-tool-fs 或独立包注册 schema，并声明 UI 呈现意图（read-card / diff-card）。
  • 观察持久化：观察状态跨会话持久化是留待未来的扩展点；当前恢复的会话必须重读。

参考资料 ​

本文档为学习用途的原创讲解，基于 MIT 许可的开源项目 deepseek-ai/deepseek-harness 编写；所有引用均注明出处。

Copyright © 2025 DeepSeek Harness 学习站