export interface FsTarget {  targetKey: FsTargetKey  // 不透明键：本地后端是 realpath，远程后端可以是 URI/文件 ID  displayPath: string    // 给模型/UI 看的路径——两个字段刻意分开}export interface FsInfo {  version: FsVersion      // 目标此刻的新鲜度令牌，是写守卫的比对基准  type: 'file' | 'directory' | 'other'  // 让策略层在读之前就能拒绝目录/特殊文件  size?: number          // 字节数：据此选 readText 还是 streamText，不用靠失败探测}

export type FsWriteIntent =  | { kind: 'createIfAbsent' }             // 只允许"创建"：目标已存在 → FS_NOT_OBSERVED  | { kind: 'replaceIfVersion'; version: FsVersion }  // 只允许"替换"：版本不符/文件消失 → FS_STALE_VERSION

abstract writeText(  target: FsTarget,  content: string,  expected?: FsWriteIntent,        // 守卫意图；省略 = 无条件创建或覆盖  signal?: AbortSignal,  sandboxPolicy?: SandboxExecutionPolicy, // 每次调用的沙箱模式 + workspace 根): Promise<FsWriteOutcome>abstract editText(  target: FsTarget,  edit: FsEditRequest,           // 字面量 oldString/newString/replaceAll  expected?: { version: FsVersion }, // 版本守卫：先查版本再匹配字面量  signal?: AbortSignal,  sandboxPolicy?: SandboxExecutionPolicy,): Promise<FsEditOutcome>

/** 不透明版本令牌：来自高精度身份 + 新鲜度元数据 */function versionOf(info: BigIntStats): FsVersion {  return FsVersion(`${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`)}

/** 以 targetKey 为粒度独占执行 op（同键 FIFO） */private async withLock<T>(targetKey: string, op: () => Promise<T>): Promise<T> {  const prior = this.locks.get(targetKey) ?? Promise.resolve() // 取该文件上一个操作（没有就空承诺）  const run = prior.then(op, op)  // 排在上一个之后执行；无论它成功还是失败都继续  const tail = run.then(() => undefined, () => undefined) // 吞掉本次结果/异常，给下一个等待者留干净的链尾  this.locks.set(targetKey, tail) // 更新队列尾部指针  try {    return await run  // 把本次操作真实的结果/异常返回给调用方  } finally {    if (this.locks.get(targetKey) === tail) this.locks.delete(targetKey) // 只有仍是队尾才删，避免误删新排进来的队列  }}

return this.withLock(target.targetKey, async () => {  const existing = await probe(target.targetKey) // 先 stat：存在吗？什么类型？  if (existing && existing.type !== 'file') {    throw new FsError('cannot write ...: not a regular file', 'FS_NOT_REGULAR_FILE') // 目录/特殊文件直接拒绝  }  if (expected?.kind === 'replaceIfVersion') {    // 陈旧守卫：文件必须仍存在于"所有者观察到的那个版本"    if (!existing) throw new FsError('...file no longer exists', 'FS_STALE_VERSION') // 读之后被删了    if (existing.version !== expected.version) {      throw new FsError('...file changed since it was read', 'FS_STALE_VERSION') // 版本变了 → 过期    }  } else if (expected?.kind === 'createIfAbsent' && existing) {    // createIfAbsent 撞上已存在文件 = 盲覆盖 —— 要求先读    throw new FsError('cannot overwrite existing ... without reading it first', 'FS_NOT_OBSERVED')  }  // expected 省略 = 无条件写，但依然走下面的原子发布路径

const stagingDirName = `.${basename(absolutePath)}.${process.pid}.${randomUUID()}.tmpdir`await mkdir(stagingDir, { mode: 0o700 }) // 在目标同目录建私有暂存区（同一文件系统 → rename 才是原子的）await chmod(stagingDir, 0o700)  // 仅属主可读写：半成品内容对他人不可见handle = await open(tempPath, 'wx', 0o600) // wx = 排他创建，已存在即失败；初始权限 0600await handle.writeFile(content, { encoding: 'utf8' })await handle.sync()  // fsync 落盘后才允许发布 —— 断电不会留下半截文件if (mode !== undefined) await handle.chmod(mode) // 恢复原文件的权限位（如 0644）if (createIfAbsent !== undefined) {  await linkFile(tempPath, absolutePath) // 硬链接发布：目标已存在则失败 → 天然实现"绝不覆盖"} else {  await rename(tempPath, absolutePath) // POSIX 原子替换}await removeStagingDir(stagingDir) // 清理暂存区；此时目标已提交，清理失败不影响写入结果

writeIntent(target: FsTarget, actor: object | undefined): FsWriteIntent {  const owner = this.owner(actor) // 从不透明 actor 里取出会话（agent.session）作为状态归属  const prior = owner ? this.get(owner, target.targetKey) : undefined // 查该会话对这个文件的观察记录  return prior?.kind === 'present'    ? { kind: 'replaceIfVersion', version: prior.version } // 读过 → 按"当时看到的版本"允许替换    : { kind: 'createIfAbsent' }  // 没读过/确认不存在 → 只许创建，不许覆盖}editIntent(target: FsTarget, actor: object | undefined): { version: FsVersion } {  if (!owner || prior === undefined) {    throw new FsError(`edit requires reading "..." first`, 'FS_NOT_OBSERVED') // 没读过 → edit 直接拒绝  }  if (prior.kind === 'absent') {    throw new FsError('cannot edit ...: not found', 'FS_NOT_FOUND') // 确认过不存在 → 报 not found  }  return { version: prior.version } // 用观察到的版本做 CAS 基准}

export function apply(ctx: Context): void {  const gate = new ObservedStateGate() // 每次 apply() 一个实例，dispose 时可整体清空  ctx.effect(() => () => gate.clear(), 'fs-observation-policy observed-state teardown') // HMR 安全：重载即清状态  // fs/write-intent：waterfall 单槽决策 —— 占住这个槽，不调 next()  ctx.on('fs/write-intent', (target, actor) =>    Promise.resolve().then(() => gate.writeIntent(target, actor))) // 延迟到微任务：throw 变成 reject，不穿透 waterfall  // fs/edit-intent：同理占槽  ctx.on('fs/edit-intent', (target, actor) =>    Promise.resolve().then(() => gate.editIntent(target, actor)))  // fs/observed 必须同步且不抛错：emit 不 await promise，且此时变更已提交  ctx.on('fs/observed', (target, observation, actor) => {    gate.observe(target, observation, actor)  })}

async execute(args: WriteToolArgs, exec) {  const input = parseWriteArgs(args) // file_path 必须非空；content 允许为空（写空文件是合法的）  // 先解析本次调用的沙箱策略：已批准的升级 > 会话默认 > 后端默认  const sandboxPolicy = await sandbox.resolvePolicy('write', args, exec)  // 相对路径按"会话 cwd"解析，而不是服务进程的启动目录  const target = await ctx.fs.resolve(input.filePath,    sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot))  // 单槽决策：策略插件给出 createIfAbsent/replaceIfVersion；没有策略则 undefined（无条件）  const intent = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)  let outcome: FsWriteOutcome  try {    outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal, sandboxPolicy)  } catch (error: unknown) {    // 沙箱拒绝 → [sandbox: ...] 标记（和 bash 工具同一套词汇）；stale/not-observed → 附带补救提示    throw remediateFsError(sandbox.mapError(error, sandboxPolicy))  }  // 记录"present + 新版本"观察（没有策略插件监听时是 no-op）  ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)  return { path: target.displayPath, operation: outcome.operation,    before: outcome.before, after: outcome.after }}

export function sessionCwd(exec: ToolExecution, requestedPath: string): string | undefined {  const cwd = exec.agent?.session.header.cwd // 取"发起调用的 agent 的会话"里记录的 workspace  if (cwd === undefined || (!PARENT_PATH_SEGMENT.test(cwd) && !PARENT_PATH_SEGMENT.test(requestedPath))) return cwd  return canonicalPath(cwd) // 路径含 .. 时先规范化：防止符号链接的 cwd 泄露文件系统身份}

async resolvePolicy(toolName, args, exec): Promise<SandboxExecutionPolicy | undefined> {  validateEscalationArgs(args.sandbox_permissions, args.justification) // 两个字段必须成对出现  const standingPolicy = this.policy?.resolve({ ... }) // 会话的常设沙箱模式  if (args.sandbox_permissions === undefined || args.justification === undefined) {    return standingPolicy // 没请求升级 → 直接用常设策略  }  // 请求了更宽的模式：必须走用户审批，且只允许"严格更宽"  const approvedMode = await approveEscalation(    { requestedMode: args.sandbox_permissions, justification: args.justification,      effectiveMode: policy.mode, subject: 'operation' },    { approver: this.ctx.get('approval'), agent: exec.agent, callId: exec.callId, ... })  return { ...policy, mode: approvedMode } // 一次性更宽重试，不改变会话默认}

write 调用全链路（一次完整的数据流）

模型 → write(file_path, content)

↓

dsh-tool-fs / executesandbox.resolvePolicy → fs.resolve(会话 cwd) → waterfall「fs/write-intent」

↓

dsh-fs-observation-policy / gate查 WeakMap[会话][targetKey] → present? replaceIfVersion(v) : createIfAbsent

↓

dsh-fs-local / writeText（withLock 临界区）probe → 版本比对 → staging(0o700) + temp(wx,0o600) + sync → link/rename 原子发布

↓

emit「fs/observed」(present, 新版本) → gate 更新观察记录返回 { path, operation, before, after } → UI diff 卡片 + 模型确认文本