DSH plugin 文件系统 seam：FsTarget、FsErrorCode 与自定义后端

DSH plugin 的文件系统 seam 有一个反直觉的设计：目标标识是不透明的，消费方不该把它当路径。 resolve() 把用户路径解析成 FsTarget，里面 displayPath 可以展示，但 targetKey 是品牌化 id——本地后端用类 realpath 字符串，远程后端可能用 URI 或文件 id。写与编辑则靠另一个不透明令牌 FsVersion 做新鲜度守卫，策略插件记录它、比较它，但谁都不解释它的内容。

这套设计让「换后端」不牵动工具与策略：dsh-fs-local 换成远程实现，工具 schema 与审批逻辑都不用改。

DSH plugin 文件系统 seam 的四个部件

一句话结论：服务定义、后端、观测策略、工具消费方各管一层，替换后端不改变策略或工具 schema。

1. 没有策略插件时：write 无条件创建或覆盖，edit 无条件替换字面文本。
2. 策略插件通过事件介入：它裁决 fs/* waterfall，而不是提供策略方法。
3. 移除策略不会坏工具：工具调用 ctx.fs 并分发事件，不依赖策略服务。
4. 默认应当加载：加载了 dsh-tool-fs 的部署也应加载观测策略，让默认行为是「先读后写」。
5. 在主干之外：文件系统属于可选能力，agent loop 不依赖它。

DSH plugin 的 FsTarget 与 FsVersion：两个不透明标识

一句话结论：路径只在 resolve 时出现一次，之后都用 FsTarget；版本令牌只用于守卫，不用于解读。

interface FsTarget {
  targetKey: FsTargetKey    // 不透明，禁止解析
  displayPath: string       // 可展示
}

1. 跨能力坐标：需要与子进程共享执行世界时，用 processPath(target)、processPathFromHostPath(hostPath)、fileUrl(target)、contains(parent, child)，而不是自己拼路径。
2. 版本令牌：FsVersion 由后端产生，策略插件存储并比较；消费方只看相关元数据。
3. 为什么这样设计：远程后端的「路径」可能是 URI 或文件 id，把标识当路径就锁死了后端。
4. 验证：换一个后端跑同一套工具调用，displayPath 变了但调用约定不变——说明你没依赖路径形态。

DSH plugin 的读取路径：stat、lstat、listDir 与有上限的 readBytes

一句话结论：stat 只给元数据；需要信任边界时先 lstat 再 resolve；字节读取必须有上限。

1. stat 返回元数据：version、type（file/directory/other）、可选 size；目标不存在返回 undefined。
2. 用 type 提前拒绝：读取前先拒绝目录与特殊文件，别等读取失败。
3. 用 size 选读法：文本消费方据此选择 readText 或 streamText，不需要靠失败探测。
4. readBytes 必填上限：readBytes(target, signal, maxBytes) 的超限会以 FS_TOO_LARGE 失败，而不是截断或无界缓冲。
5. lstat 不跟随链接：resolve 会跟随 symlink 以产生稳定标识；有信任规则的消费方可以先 lstat，在解析前拒绝 symlink。
6. listDir 只给元数据：按稳定名称顺序返回直接子项，不读内容；权限或 IO 失败以 FS_PERMISSION_DENIED 或 FS_IO_ERROR 让整个列表失败。

DSH plugin 的写入与编辑守卫：FsWriteIntent 与原子替换

一句话结论：守卫可选，省略即无条件；带守卫时先验版本再改内容，整个过程在一个临界区里。

type FsWriteIntent =
  | { kind: 'createIfAbsent' }
  | { kind: 'replaceIfVersion'; version: FsVersion }

1. createIfAbsent：目标已存在就以 FS_NOT_OBSERVED 拒绝——即使它在初始探测之后才出现，也拒绝。
2. replaceIfVersion：仅在目标存在且版本匹配时替换，否则 FS_STALE_VERSION。
3. 省略守卫：无条件创建或覆盖，不是一个隐藏的第三种意图。
4. 写入结果：FsWriteOutcome 带 operation（create/update）、新版本、before（不存在时为 null）与 after，两者都做 LF 归一化，作为差异计算的基础。
5. editText 是提供方级操作：不是「读 + 写」的组合；带守卫时先校验版本再字面匹配，oldString 必须非空，replaceAll 控制替换全部还是要求唯一匹配。
6. 原子性：匹配、行尾处理、陈旧检查与替换在同一个变更临界区内完成。

DSH plugin 的策略事件：两个 waterfall 与一个记录事件

一句话结论：write/edit 意图是单槽决策 waterfall，观测结果是即发即弃通知——监听方必须同步且只做副作用。

1. fs/write-intent 与 fs/edit-intent：单槽 waterfall；工具分发时附带默认 thunk（返回 undefined 即裸提供方），监听方完全决策而不调用 next()。
2. 先到先得：slot 按注册顺序占用，由策略插件占据是部署约定而非强制不变式。
3. fs/observed：携带 FsObservation（present 带版本 / absent），通过普通 ctx.emit 分发。
4. 监听方纪律：必须同步、只产生副作用——工具不会捕获该 emit 抛出的异常，抛错可能取代原本待返回的错误，甚至让已成功的变更返回 isError。
5. 观测的所有者：策略插件通过收窄事件里的不透明 actor 推导，不需要导入工具、agent 或会话包。

DSH plugin 的 FsErrorCode 与排查注意事项

一句话结论：文件系统问题先看错误码，再看是「守卫拒绝」还是「后端失败」。

1. FS_NOT_OBSERVED → 带 createIfAbsent 时目标已存在，改用 replace 或有条件创建。
2. FS_STALE_VERSION → 版本过期或目标缺失，重新 resolve 再试。
3. FS_TOO_LARGE → 超过 readBytes 的 maxBytes，改流式或提高上限。
4. FS_PERMISSION_DENIED / FS_IO_ERROR → 后端层问题，不是策略拒绝。
5. 编辑报版本错而不是匹配失败 → 正常，守卫先验版本。
6. 修复状态如实：本文的四部件分工、两个不透明标识、守卫语义与事件纪律均取自官方「文件系统」页面；错误码全集与接口签名以该页 Cordis API 与你所用版本为准。

来源：文件系统、dsh-fs 源码、dsh-fs-observation-policy。