@deepseek-ai/dsh-fs-policy

English | 中文

fs-policy 插件：它在 ctx.fs 提供方 seam（@deepseek-ai/dsh-fs）之上增加已观察状态、编辑前读取和版本防护的写入/编辑；它通过 fs/* 事件门禁参与，不是通过方法服务。该插件不注册 ctx.fsPolicy 服务，也没有公开的 read/write/edit/resolve 方法。它是文件系统栈的政策层：不是可替换 seam，而是不应位于 FileSystem 提供方基类上的政策。

import type { Context } from 'cordis'
import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'

declare const ctx: Context

// No service to inject — this plugin only registers the three fs/* listeners.
// Load it alongside a ctx.fs provider (e.g. @deepseek-ai/dsh-fs-local) and the
// @deepseek-ai/dsh-tool-fs tools; the tools dispatch the fs/* events this plugin
// decides. Order does not matter for resolution (no inject), but the policy
// listener should be the first decider registered for the fs/*-intent slots.
await ctx.plugin(FsPolicy)

四层拆分

层	包	角色
工具/执行器	`@deepseek-ai/dsh-tool-fs`	面向模型的 schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件
政策	`@deepseek-ai/dsh-fs-policy`（本包）	已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务）
提供方 seam	`@deepseek-ai/dsh-fs`	`ctx.fs`：文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇
提供方	`@deepseek-ai/dsh-fs-local`	`ctx.fs` 的本地实现

门禁的参与方式

三个 fs/* 事件（由 @deepseek-ai/dsh-fs 声明，@deepseek-ai/dsh-tool-fs 分派）：

事件	本插件的监听器
`fs/write-intent`	先前未观察 → `{ kind: 'createIfAbsent' }`；先前已观察 → `{ kind: 'replaceIfVersion', version: vObserved }`。单槽决策；不调用 `next()`。
`fs/edit-intent`	要求该所有者先前已观察，否则抛出 `FS_NOT_OBSERVED`；返回 `{ version: vObserved }` 作为 CAS 基础。单槽决策；不调用 `next()`。
`fs/observed`	为该所有者与目标记录 `{ version }`。同步、只有副作用的 `WeakMap.set`。

已观察状态是先前观察记录；新鲜度由提供方 CAS 保证

已观察状态是一张从弱引用所有者映射到目标版本的表，每次读取或变更成功后都会更新；记录存在本身就是先前观察凭据。插件不执行文件系统 I/O：它把观察到的版本提供给提供方的原子变更防护。窗口读取会观察整个文件的版本，因此只有文件保持不变时才允许后续的定向编辑。插件 dispose（资源释放）时会丢弃状态，并且不会跨会话持久化。

单槽、先到者胜

fs/write-intent/fs/edit-intent 槽位只容纳一个决策器；本插件会完整决策，不调用 next()。槽位按注册顺序先到者胜；由本插件拥有槽位只是默认部署约定，不是事件强制的不变式（更早注册或通过 prepend 注册的决策器会胜出）。这不是可组合的授权链；分层权限/审计/沙箱拦截属于 tools/execute。

不与方法耦合

由于插件只通过事件影响外部世界，移除它不会在服务注入边界破坏 @deepseek-ai/dsh-tool-fs：工具会直接落到裸 ctx.fs 提供方（无条件写入/编辑，无已观察状态）。重新加载则会再次叠加政策。相比必需的方法服务，这种可平稳增删的性质正是事件门禁的全部目的。

模型体验

文件系统工具结果

模型看到的内容

该插件不添加提示词或 schema。编辑前未读取时，它会以代码 FS_NOT_OBSERVED 和精确消息 edit requires reading "<path>" first 拒绝。观察版本陈旧的防护变更会传播由提供方拥有的 FS_STALE_VERSION 错误。dsh-tool-fs拥有面向模型的错误包装；观察状态绝不会显示。

Token 影响

允许的操作除了普通工具结果外不增加 token。拒绝会添加少量保留的错误结果，并避免产生成功 payload。

KV Cache 影响

仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。

已知限制与延期工作

已观察状态无法跨会话恢复：WeakMap 记录的持久化延期处理，因此恢复的会话必须重新读取文件，才能执行防护写入/编辑。
没有 agent 会话的参与者绝无法满足政策：它们的编辑会抛出 FS_NOT_OBSERVED，写入总会解析为 createIfAbsent，因此非 agent（智能体）调用方无法通过门禁覆盖现有文件。
直接 ctx.fs 读取不会发出 fs/observed：在 read 工具之外读取的文件仍未观察；后续防护编辑会以 FS_NOT_OBSERVED 拒绝，直到工具读取该文件。
授权依据是版本新鲜度，而非视图完整性：任何窗口读取都会授权对未变文件执行全文件覆盖，这有意弱于完整视图规则（见 seam 拆分 Agent Note）。

5.2 KiB Raw Blame History Unescape Escape