ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 文件系统 seam:补丁语法、写入守卫与 fs 策略事件到底怎么配合用

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness文件系统补丁写入守卫
自定义文件后端后,补丁应用结果和守卫行为与内置实现不一致。本文讲 FsTarget 的不透明身份、dsh-fs-patch 的补丁语法与失败结构、写入与编辑守卫的判定顺序,以及 fs/* 策略事件的分工。

补丁打不上,或者守卫没拦住,通常不是匹配算法的问题,而是你把不透明身份当成了路径。 DSH plugin 的文件系统 seam 先用 resolve() 把路径变成 FsTarget,之后每个操作只认这个身份。理解这条边界,比调补丁上下文更有效。 DSH插件 换文件后端时,守住不透明身份这条线,守卫与补丁行为就不会漂。

三个角色加一个可选策略

文件系统属于可选能力,替换后端不会改变策略或工具 schema。(来源) 角色分工:

  1. dsh-fs — 拥有 ctx.fs 与受防护的文件变更操作;
  2. dsh-fs-local — 实现本地磁盘后端;
  3. dsh-fs-observation-policy — 记录观测到的存在或缺失状态,并通过事件而非服务添加新鲜度规则;
  4. dsh-tool-fs — 执行面向模型的 read/write/edit 并渲染窗口。

纯库 dsh-fs-patch 提供补丁解析与文本应用。整套能力位于 agent 循环主干之外,所以替换后端不会改变工具 schema,也不会改变策略行为。

策略插件是可选的:没有它时,FileSystem 服务定义、一个提供方与 dsh-tool-fs 就构成完整且不受约束的 seam——write 无条件创建或覆盖,edit 无条件替换字面文本。启用它后,操作会经过 fs/* waterfall 裁决。随发行版交付的组合里,dsh-base 的 fs-observation-policy 行写着 disabled: true,需要“先读后写/编辑”的部署把它改成 disabled: false。

移除策略插件不会破坏工具,因为工具调用 ctx.fs 并分发事件,而不是直接调用策略方法。这条设计让策略成为可插拔的装饰,而不是硬依赖。

目标是不透明身份,不是路径

displayPath 可以展示,targetKey 与 FsVersion 都不许解析。(来源)

每个操作首先将用户提供的路径解析为不透明的后端目标。消费方可以显示 displayPath,但禁止解析 targetKey——本地后端用类 realpath 字符串,远程后端可能用工作区 URI 或文件 id。

与文件系统共享执行世界的消费方应当通过提供方取坐标,而不是自己解释身份:processPath(target) 返回子进程可打开的规范化绝对路径;processPathFromHostPath(hostPath) 只在共享相应宿主文件时映射;fileUrl(target) 返回提供方平台语法的 file: URI;contains(parent, child) 检查身份相等或后代包含。

stat 只返回元数据、从不返回内容,目标不存在时返回 undefined。三个字段各有用途:version 是新鲜度令牌;type 让消费方在读取前拒绝目录和特殊文件;size 让文本消费方无需通过失败探测就能选择 readText 还是 streamText。

原始字节消费方用 readBytes(target, signal, maxBytes),其必填的完整内容上限会让已知或读取中发现的超限以 FS_TOO_LARGE 失败,而不是截断结果或无界缓冲。

lstat 是解析前的信任边界检查

resolve() 会跟随符号链接,lstat 不会,两者用途相反。(来源)

lstat 是路径级、不跟随最终路径组件的元数据原语。它接收路径而不是 FsTarget,因为 resolve() 会有意跟随 symlink 以产生稳定标识。

这条差异给需要信任边界规则的消费方留了入口:在解析前先 lstat,看到 type: 'symlink' 就拒绝。官方在守卫章节里也提醒——目标已跟随符号链接,因此想拒绝符号链接源,调用方必须在 resolve 前检查。

listDir 按稳定名称顺序返回直接子条目,每项带 basename、类型、已解析目标与廉价元数据。它禁止读取内容,因此 size 只对普通文件有意义;损坏或消失的子项可以作为 other 返回且不带元数据,而权限或后端 I/O 失败会让整个列表以 FS_PERMISSION_DENIED 或 FS_IO_ERROR 失败。

补丁解析与应用是纯库

解析产出可序列化操作,应用要么给完整新文本,要么给结构化失败。(来源)

dsh-fs-patch 把完整补丁文本解析为可序列化的操作,路径保持为未解析的字符串;applyHunks 把 hunk 应用于调用方提供的 LF 规范化文本,返回完整新文本或结构化匹配失败。

PatchHunk 的字段值得逐个对上:lineNumber 是补丁输入里的一基行号;context 是 @@ 之后的文本,作搜索锚点;oldLines 与 newLines 不含前缀与行尾;isEndOfFile 表示后面跟着 *** End of File。

PatchOperation 只有三种:add、delete、update。移动被表达为带 moveTo 的 update,不是第四种操作。add 的 content 用 LF 连接,每个新增行都带结尾 LF。

失败结构是 HunkApplyFailure:hunkLineNumber、stage(context 或 oldLines)、searchStart 与 pattern。ApplyHunksResult 的失败分支不含任何部分更新文本——这一点很重要,调用方不需要自己回滚半个结果。

写入与编辑守卫

同名守卫覆盖补丁、删除与移动,但每种操作观察的阶段不同。(来源)

操作意图事件成功观察
patchTextfs/edit-intent目标存在于返回的版本
deleteFilefs/delete-intent源缺失
moveFile 源fs/edit-intent仅 sourceDeleted 为 true 时记录源缺失
moveFile 目标fs/write-intent目标存在于 destination.version

几条硬规则:补丁、删除与移动的源必须是普通文件;源缺失或版本陈旧报 FS_STALE_VERSION;补丁在变更锁内对 LF 规范化文本匹配,不匹配报 FS_PATCH_MISMATCH 并带上 hunk 行号与阶段;移动以 FS_SAME_TARGET 拒绝相同目标 key,并对目标使用写入守卫,同时保留源的行尾风格与模式。

移动是两个效果,不是一个:目标可能已发布而源删除失败,此时返回 sourceDeleted: false 与 sourceFailure。本地移动在暂存目标前检查取消,随后提供方完成两端效果并报告结果。

writeText 与 editText 的版本守卫都是可选的。省略守卫时执行无条件的裸提供方变更;提供守卫时才有条件检查。FsWriteIntent 只有两支:createIfAbsent 在目标已存在时以 FS_NOT_OBSERVED 拒绝——即使目标是在提供方初始探测后才出现,也必须拒绝,因为发布操作本身不得替换;replaceIfVersion 在缺失或版本不匹配时报 FS_STALE_VERSION。

“无守卫”通过省略 expected 表达,不是联合类型的第三支。FsWriteOutcome 的 before 是 LF 规范化存储文本,不是 diff;文件不存在或后端拒绝提供上下文基底(二进制、非 UTF-8、任一侧达到独占上限)时为 null,此时消费方退回整文件 diff。

editText 是提供方级别的变更操作,不是在别处组合的 read 加 write。带守卫时,它在字面匹配之前先验证预期版本,所以对陈旧内容的编辑报 FS_STALE_VERSION,而不是对更新内容的匹配失败;不带守卫时编辑当前内容。两条路径都在一个变更临界区内完成匹配、行尾处理、陈旧检查与原子替换,目标缺失时都报 FS_STALE_VERSION。

策略事件让“先读后写”成为可选

策略插件靠 fs/* waterfall 裁决,而不是替换方法。(来源)

dsh-fs-observation-policy 记录观测到的存在或缺失状态,并通过事件添加新鲜度规则。它改变的是“这次操作能不能通过”,不改变工具的调用方式。

这条设计带来一个排查顺序:先确认工具是不是真的在调 ctx.fs(而不是绕过 seam 直接写盘),再确认策略插件是否启用,最后才看守卫判定。dsh-base 默认禁用该插件,所以“守卫没生效”十有八九是配置问题。

同一条规则也解释了为什么替换后端不会改变策略:策略挂在事件上,后端只负责解析身份与执行变更,两者解耦。

验证:成功补丁与被拒绝写入

验证要分别覆盖补丁失败结构与守卫拒绝路径,不能只测成功样本。(来源) 六步:

  1. resolve() 一个文件路径,断言拿到 targetKey 与 displayPath,且后续操作只用前者。
  2. 应用一个上下文不匹配的补丁,断言 ok 为假、stage 指明失败阶段、没有部分更新文本。
  3. 用 createIfAbsent 写一个已存在的文件,断言报 FS_NOT_OBSERVED。
  4. 用旧 version 调 replaceIfVersion,断言报 FS_STALE_VERSION。
  5. 对陈旧内容调带守卫的 editText,断言报 FS_STALE_VERSION 而不是匹配失败。
  6. 移动到一个与源相同的目标 key,断言报 FS_SAME_TARGET,且源文件仍完整。

如果第 2 步拿到的 stage 与预期不符,先看 pattern 与 searchStart:锚点搜索与旧行搜索是两个阶段,混在一起判断会误导。

文件系统与沙箱策略的交界,可以对照沙箱逐调用策略;后端替换的完整契约见文件系统 seam 概览。

一句话收束: 身份不透明、路径只用于展示,补丁失败不带半成品,守卫靠省略表达无条件,策略挂在事件而不是方法上。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 targetKey 能当本地路径用吗?

不能,DSH plugin 明确禁止解析它。DSH plugin 的 targetKey 是不透明品牌化 id,本地后端用类 realpath 字符串,远程后端可能用工作区 URI 或文件 id;展示用 displayPath,跨能力坐标用 processPath。

DSH plugin 的 writeText 省略守卫会发生什么?

DSH plugin 会执行无条件的裸提供方变更,即创建或覆盖。DSH plugin 用省略 expected 表达无守卫,而不是在联合类型里再加一个分支。

DSH plugin 编辑陈旧内容时,报的是版本错误还是匹配失败?

DSH plugin 报 FS_STALE_VERSION,而不是匹配失败。DSH plugin 的 editText 在字面匹配之前先验证预期版本,所以陈旧内容会先被版本检查拦下。

DSH plugin 移除观察策略插件之后,读写工具还能正常用吗?

能,DSH plugin 的工具调用 ctx.fs 并分发事件,不调用策略方法。DSH plugin 在没有策略插件时,write 无条件创建或覆盖,edit 无条件替换字面文本。

相关术语

FsTarget
FsTarget 是后端解析出的稳定身份,含不透明 targetKey 与用于展示的 displayPath。— packages/fs/fs/src/types.ts
FsVersion
FsVersion 是不透明的文件版本令牌,即写入或编辑守卫所比对的新鲜度凭证,消费方不得解释其内容。— packages/fs/fs/src/types.ts
FsWriteIntent
FsWriteIntent 是带守卫的写入意图,只有 createIfAbsent 与 replaceIfVersion 两种取值。— packages/fs/fs/src/types.ts
ApplyHunksResult
ApplyHunksResult 是补丁应用结果,要么返回完整新文本,要么返回不含部分更新文本的匹配失败。— packages/fs/fs/src/types.ts

来源