文件系统：事件 gate 型 seam 的样板

示例本次示例：模型写文件的意图闸门

# 模型：write({path:'src/auth.ts', content:'...'})
# → tool-fs 执行（inject=['tools','fs','systemPrompt']）
# → 写之前发 fs/write-intent（fs/src/index.ts:58，waterfall）：
#   payload = { target: {path:'src/auth.ts'}, actor: exec.agent }
# fs-observation-policy 的监听器（fs-observation-policy/src/index.ts:116-119）：
#   占据决策槽、不调 next() → 策略判定：
#     只读检查 → 放行（返回 intent）
#     写到工作区外 → 拒绝（返回 undefined 或改写）
# 判定结果回传 tool-fs → 执行或拒绝 → tool/result
# 对比 shell（15 页）：这里没有 ctx.get('policy') 调用——策略是「拦」下来的

# 如果第二个插件也监听 fs/write-intent 且不调 next：
# 它短路掉第一个 policy 的判定（08 页 waterfall 语义）
# → 决策冲突 → 第一个 policy 形同虚设
# 教训：事件 gate 型 policy 的组合必须靠 policy 内部编排，
# 不能指望事件链叠加（26 页易错点）

§1挂载条目

• fs-observation-policy → dsh-fs-observation-policy——写意图的观察策略（事件 gate 的消费者）
• tool-fs → dsh-tool-fs（1517 行）——文件读写工具（inject = ['tools','fs','systemPrompt']，src/index.ts:22）
• tool-fs-search → dsh-tool-fs-search（1578 行）——文件搜索工具
• tool-str-replace-editor → dsh-tool-str-replace-editor（553 行）——字符串替换编辑
• fs-sandbox → dsh-fs-sandbox——沙箱化 fs 提供方（static inject = ['sandboxPolicy']，src/index.ts:60）

§2包文件地图

§3机制：事件 gate 的完整形态

1. provider 发意图：fs 工具要写文件前，发出 fs/write-intent（waterfall）——携带目标与 actor。
2. policy 拦截：fs-observation-policy 的监听器不调 next()（占据决策槽）——返回策略的判定（放行/改写/拒绝）。这就是「事件 gate」：policy 不通过 ctx.get 被调用，而是通过事件链被拦下来。
3. 观察回传：fs/observed 报告实际发生的变化（供注入、UI 更新等下游）。

与 15 页的 shell 对比：shell 的连接是 ctx.shell.resolve → run（调用链），fs 的连接是 intent → 事件 → policy（拦截链）。前者适合「能力替换」，后者适合「行为管制」。

§4关键代码

58    'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
86export abstract class FileSystem extends Service {

116  // fs/write-intent: occupy the single decision slot — do NOT call next().
119  ctx.on('fs/write-intent', (target, actor) => Promise.resolve().then(() => gate.writeIntent(target, actor)))

§5易错点