DSH plugin 文件系统 seam:补丁语法、写入守卫与 fs 策略事件到底怎么配合用
补丁打不上,或者守卫没拦住,通常不是匹配算法的问题,而是你把不透明身份当成了路径。 DSH plugin 的文件系统 seam 先用 resolve() 把路径变成 FsTarget,之后每个操作只认这个身份。理解这条边界,比调补丁上下文更有效。 DSH插件 换文件后端时,守住不透明身份这条线,守卫与补丁行为就不会漂。
三个角色加一个可选策略
文件系统属于可选能力,替换后端不会改变策略或工具 schema。(来源) 角色分工:
dsh-fs— 拥有ctx.fs与受防护的文件变更操作;dsh-fs-local— 实现本地磁盘后端;dsh-fs-observation-policy— 记录观测到的存在或缺失状态,并通过事件而非服务添加新鲜度规则;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 的失败分支不含任何部分更新文本——这一点很重要,调用方不需要自己回滚半个结果。
写入与编辑守卫
同名守卫覆盖补丁、删除与移动,但每种操作观察的阶段不同。(来源)
| 操作 | 意图事件 | 成功观察 |
|---|---|---|
patchText | fs/edit-intent | 目标存在于返回的版本 |
deleteFile | fs/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 默认禁用该插件,所以“守卫没生效”十有八九是配置问题。
同一条规则也解释了为什么替换后端不会改变策略:策略挂在事件上,后端只负责解析身份与执行变更,两者解耦。
验证:成功补丁与被拒绝写入
验证要分别覆盖补丁失败结构与守卫拒绝路径,不能只测成功样本。(来源) 六步:
resolve()一个文件路径,断言拿到targetKey与displayPath,且后续操作只用前者。- 应用一个上下文不匹配的补丁,断言
ok为假、stage指明失败阶段、没有部分更新文本。 - 用
createIfAbsent写一个已存在的文件,断言报FS_NOT_OBSERVED。 - 用旧
version调replaceIfVersion,断言报FS_STALE_VERSION。 - 对陈旧内容调带守卫的
editText,断言报FS_STALE_VERSION而不是匹配失败。 - 移动到一个与源相同的目标 key,断言报
FS_SAME_TARGET,且源文件仍完整。
如果第 2 步拿到的 stage 与预期不符,先看 pattern 与 searchStart:锚点搜索与旧行搜索是两个阶段,混在一起判断会误导。
文件系统与沙箱策略的交界,可以对照沙箱逐调用策略;后端替换的完整契约见文件系统 seam 概览。
一句话收束: 身份不透明、路径只用于展示,补丁失败不带半成品,守卫靠省略表达无条件,策略挂在事件而不是方法上。
常见问题
不能,DSH plugin 明确禁止解析它。DSH plugin 的 targetKey 是不透明品牌化 id,本地后端用类 realpath 字符串,远程后端可能用工作区 URI 或文件 id;展示用 displayPath,跨能力坐标用 processPath。
DSH plugin 会执行无条件的裸提供方变更,即创建或覆盖。DSH plugin 用省略 expected 表达无守卫,而不是在联合类型里再加一个分支。
DSH plugin 报 FS_STALE_VERSION,而不是匹配失败。DSH plugin 的 editText 在字面匹配之前先验证预期版本,所以陈旧内容会先被版本检查拦下。
能,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
来源
- DeepSeek Harness 官方参考 - 文件系统· deepseek-ai
- packages/fs/fs/src/types.ts· deepseek-ai