DeepSeek Harness 文件系统接缝清理实录从 fs seam 中移除只写字段与无效路由旋钮【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇以 DeepSeek HarnessEverything is a Plugin仓库中一条已实施的架构简化记录.agents/notes/archived/simplification/2026-07-04-prune-write-only-fs-surface.zh.md为核心还原一次针对**文件系统能力接缝filesystem seam**的精准瘦身删除四处每次调用都填充、却无人读取的只写字段与一个失效的路由配置旋钮。读者将看到fs seam 拆分成四个包后旧接口形态残留了哪些死代码团队如何通过零读取者证据决定删与留以及收窄后的类型形状如何反过来约束测试 fake 与文档同步演进。背景fs seam 拆分后留下的旧形态残留DeepSeek Harness 的可选文件系统能力由四个包构成见 filesystem.md 的系统描述dsh-fs —— 拥有ctx.fs抽象接缝与原子文本操作原语readText/streamText/readBytes/writeText/editText等类型词汇定义在 types.tsdsh-fs-local —— 本地磁盘实现dsh-fs-observation-policy —— 通过事件而非服务来记录观察到的存在/缺失并附加新鲜度规则read-before-write/editdsh-tool-fs —— 直接执行面向模型的 read/write/edit 工具调用并渲染窗口。在 fs seam 拆分 之后读取路由与策略逻辑已从后端前移到dsh-tool-fs与dsh-fs-policy。但接口层面有四处仍保留着拆分前的形态——每次调用都填充却全仓库无人读取。这正是本次清理的目标。四处只写表面逐个拆解1.dsh-fs-local的STREAM_MIN_SIZEFsIoInternals.streamMinSize同一事实的两份镜像最初的问题位置在packages/fs/fs-local/src/fsio.ts经packages/fs/fs-local/src/index.ts重导出。该常量连同streamMinSize配置项在本次变更之前已被禁止硬编码可调参数审计移除——审计将路由阈值改成了dsh-tool-fs的readStreamMinSize配置本笔记记录它只是为了完整呈现整次清理。其核心教训是后端没有读取路由。readWholeText/streamWholeText是调用方自行选择的两个独立原语真正的路由常量位于消费方 packages/fs/tool-fs/src/read.ts即/** Default streaming threshold (the readStreamMinSize config): files at or * above this size stream; smaller files read whole into memory. */ export const STREAM_MIN_SIZE 10 * 1024 * 1024消费方在execute中与info.size比较完成路由read.ts// Stream when the file is large OR size is unknown, so a size-less backend // never buffers an arbitrarily large file. const chunks info.size undefined || info.size caps.streamMinSize ? await ctx.fs.streamText(target, exec.signal) : [await ctx.fs.readText(target, exec.signal)]也就是说10 MiB 流式阈值这一事实存在两份镜像后端那份无人读取属于死代码且该旋钮的 JSDoc 声称提供一个实际不存在的 read routing 覆盖——真实路由在消费方。删除后端镜像后阈值语义唯一化避免了两处维护时的漂移风险。2.FsTarget.inputPath仅供诊断却无人消费的路径字段FsTarget是resolve()返回的稳定目标身份所有其他操作都以它入参。旧形态中它带有一个inputPath字段名义上仅供诊断但生产环境零读取者策略插件与所有错误消息使用的是targetKey/displayPath每个后端和每个测试 mock 都必须为它编造一个值凭空增加协议负担listDir的生产者暴露了语义上的摇摆目录子项拿到的是裸条目名这并不是任何人的 input。收窄后的FsTarget只剩两个真正被消费的字段types.tsexport interface FsTarget { /** Opaque key for stale guards and target lookup. */ targetKey: FsTargetKey /** Path for model/UI-facing output. May be a local absolute path, * workspace-relative path, or remote URI depending on the backend. */ displayPath: string }3.FsEditOutcome.replacements.replaceAll结果字段回显请求参数FsEditOutcome是字面量替换编辑editText的返回值。旧形态中replacements生产环境零读取者。单匹配策略本身予以保留——它由后端内部以FS_AMBIGUOUS_EDIT/FS_EDIT_NOT_FOUND错误码抛出强制执行错误类型词汇见 types.ts错误消息也保留了内部计数replaceAll仅被 packages/fs/tool-fs/src/edit.ts 中的formatEditOutput读取——而这只是工具本身已持有的replace_all参数的回声export function formatEditOutput(displayPath: string, replaceAll: boolean): string { return replaceAll ? The file ${displayPath} has been updated. All occurrences were successfully replaced. : The file ${displayPath} has been updated successfully. }精简后FsEditOutcome收窄为{ version, before, after }与FsWriteOutcome中真正由后端发现的字段对齐types.tsexport interface FsEditOutcome { /** Opaque version of the file after the edit. */ version: FsVersion /** The files content BEFORE the edit. */ before: string /** The files content AFTER the edit. */ after: string }请求侧的replaceAllFsEditRequest保持不变——它是消费者真正需要的入参编辑工具execute也继续将其透传给ctx.fs.editTextedit.ts。4.FileReadOutcome.limit.version渲染不需要、事件用不到FileReadOutcome位于 packages/fs/tool-fs/src/read-render.ts由读取工具填充。旧形态携带limit与version但formatReadOutput只渲染offset/lines/totalLines/truncatedByBytes——页脚里展示的一切Showing lines X-Y of Z、End of file都可以从lines/totalLines直接推导fs/observed事件发射直接使用info.version见 read.tsctx.emit(fs/observed, target, { kind: present, version: info.version }, exec)而不是 outcome 上的版本副本。因此FileReadOutcome最终保留为纯展示所需的窗口形状export interface FileReadOutcome { /** 1-based first line requested. */ offset: number /** Returned lines, already numbered. */ lines: FileTextLine[] /** Exact total line count in the file. */ totalLines: number /** Whether selected output hit the byte cap. */ truncatedByBytes?: true }决策摘要删什么、留什么本次变更的决策可归纳为一张清晰的删/留对照表表面处理理由dsh-fs-local的STREAM_MIN_SIZE/FsIoInternals.streamMinSize删除常量、其再导出与配置项全仓库零读取者真实路由常量在dsh-tool-fs的readStreamMinSizeFsTarget.inputPath删除生产环境零读取者每个后端与测试 mock 都要虚构值FsEditOutcome.replacements删除生产环境零读取者单匹配策略由后端错误码强制执行FsEditOutcome.replaceAll删除仅被formatEditOutput读取属于工具已持有参数的回声FsEditRequest.replaceAll保留请求侧入参编辑工具真正需要FsWriteOutcome/FsEditOutcome的version/before/after保留由后端发现并真正消费的字段FileReadOutcome.limit/.version删除渲染不需要事件发射直接用info.version随类型一同收窄的还有filesystem.md 中的相关粘贴、packages/fs/fs/README.md以及不得不虚构已删除字段的测试 fake——类型一变fake 与文档的虚构成本随之消失这正是接口瘦身带来的连锁收益。为什么不留着它们替代方案的取舍面向未来功能时每个被删字段似乎都能找到以后可能有用的理由但逐一审视后都被否决未来权限/隔离层需要解析前的路径来生成错误文本它需要的是请求本身而每个调用点仍然持有请求parseReadArgs等调用方手中的原始参数不需要靠FsTarget.inputPath传递。替换了 N 处可能成为面向模型的文本这是需要时再设计的行为变更且后端内部的计数已为其错误消息保留不必提前挂在 outcome 上。读取页脚可能展示limit页脚展示的一切已可从lines/totalLines推导无需冗余字段。反方成本却是确定的每个现有和未来的后端远程、原生都必须编造无人消费的协议字段每个测试 mock 都必须满足它们。用确定的当下成本去赌不确定的未来需求不划算。验证删除即证据验证方式非常直接——已删除表面不复存在dsh-fs-local中不再有STREAM_MIN_SIZE/streamMinSize当前仓库搜索该符号仅命中消费方dsh-tool-fs与决策一致FsTarget无inputPathFsEditOutcome无replacements/.replaceAllFileReadOutcome无limit/.version。同时请求侧replaceAllFsEditRequest与FsWriteOutcome/FsEditOutcome上的版本字段保持不变测试 fake 随类型一同收窄。由于formatEditOutput在两个replace_all分支中生成的文本都没有变化仍是那句 has been updated successfully. / All occurrences were successfully replaced.因此没有任何快照预期输出发生改动——行为完全兼容纯属表面清理。后果与后续后端不增加新义务反而卸下了四个无人消费的字段远程、原生等任何未来后端的协议实现负担变小测试 mock 的虚构成本归零。一个已知的文本层面重叠fs 发现功能glob/grep 工具见 tool-fs-search涉及相同的dsh-fs类型文件——这是文本而非设计层面的重叠可以机械地合并解决。从更广的视角看这次清理是 DeepSeek Harness 一系列只写表面审计中的一环同目录下还有 2026-06-20-prune-dead-seam-methods、2026-07-02-remove-stream-chunk-mirror 等相邻笔记。其方法论可以提炼为可复用的接缝卫生准则用零读取者说话一个字段若全仓库含源码与测试无人读取它就不是接口而是税。镜像事实必须消除同一配置阈值出现在后端与消费方就必然面临漂移把路由留在真正做决策的那一层。收窄类型时同步收窄文档与 fake类型是契约契约变则粘贴的文档片段与测试替身必须同批更新否则死代码会借文档复活。用快照验证零行为变化当输出文本逐字节不变时快照测试就是这次清理是纯删减的最强证明。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepSeek Harness 文件系统接缝清理实录：从 fs seam 中移除只写字段与无效路由旋钮
DeepSeek Harness 文件系统接缝清理实录从 fs seam 中移除只写字段与无效路由旋钮【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇以 DeepSeek HarnessEverything is a Plugin仓库中一条已实施的架构简化记录.agents/notes/archived/simplification/2026-07-04-prune-write-only-fs-surface.zh.md为核心还原一次针对**文件系统能力接缝filesystem seam**的精准瘦身删除四处每次调用都填充、却无人读取的只写字段与一个失效的路由配置旋钮。读者将看到fs seam 拆分成四个包后旧接口形态残留了哪些死代码团队如何通过零读取者证据决定删与留以及收窄后的类型形状如何反过来约束测试 fake 与文档同步演进。背景fs seam 拆分后留下的旧形态残留DeepSeek Harness 的可选文件系统能力由四个包构成见 filesystem.md 的系统描述dsh-fs —— 拥有ctx.fs抽象接缝与原子文本操作原语readText/streamText/readBytes/writeText/editText等类型词汇定义在 types.tsdsh-fs-local —— 本地磁盘实现dsh-fs-observation-policy —— 通过事件而非服务来记录观察到的存在/缺失并附加新鲜度规则read-before-write/editdsh-tool-fs —— 直接执行面向模型的 read/write/edit 工具调用并渲染窗口。在 fs seam 拆分 之后读取路由与策略逻辑已从后端前移到dsh-tool-fs与dsh-fs-policy。但接口层面有四处仍保留着拆分前的形态——每次调用都填充却全仓库无人读取。这正是本次清理的目标。四处只写表面逐个拆解1.dsh-fs-local的STREAM_MIN_SIZEFsIoInternals.streamMinSize同一事实的两份镜像最初的问题位置在packages/fs/fs-local/src/fsio.ts经packages/fs/fs-local/src/index.ts重导出。该常量连同streamMinSize配置项在本次变更之前已被禁止硬编码可调参数审计移除——审计将路由阈值改成了dsh-tool-fs的readStreamMinSize配置本笔记记录它只是为了完整呈现整次清理。其核心教训是后端没有读取路由。readWholeText/streamWholeText是调用方自行选择的两个独立原语真正的路由常量位于消费方 packages/fs/tool-fs/src/read.ts即/** Default streaming threshold (the readStreamMinSize config): files at or * above this size stream; smaller files read whole into memory. */ export const STREAM_MIN_SIZE 10 * 1024 * 1024消费方在execute中与info.size比较完成路由read.ts// Stream when the file is large OR size is unknown, so a size-less backend // never buffers an arbitrarily large file. const chunks info.size undefined || info.size caps.streamMinSize ? await ctx.fs.streamText(target, exec.signal) : [await ctx.fs.readText(target, exec.signal)]也就是说10 MiB 流式阈值这一事实存在两份镜像后端那份无人读取属于死代码且该旋钮的 JSDoc 声称提供一个实际不存在的 read routing 覆盖——真实路由在消费方。删除后端镜像后阈值语义唯一化避免了两处维护时的漂移风险。2.FsTarget.inputPath仅供诊断却无人消费的路径字段FsTarget是resolve()返回的稳定目标身份所有其他操作都以它入参。旧形态中它带有一个inputPath字段名义上仅供诊断但生产环境零读取者策略插件与所有错误消息使用的是targetKey/displayPath每个后端和每个测试 mock 都必须为它编造一个值凭空增加协议负担listDir的生产者暴露了语义上的摇摆目录子项拿到的是裸条目名这并不是任何人的 input。收窄后的FsTarget只剩两个真正被消费的字段types.tsexport interface FsTarget { /** Opaque key for stale guards and target lookup. */ targetKey: FsTargetKey /** Path for model/UI-facing output. May be a local absolute path, * workspace-relative path, or remote URI depending on the backend. */ displayPath: string }3.FsEditOutcome.replacements.replaceAll结果字段回显请求参数FsEditOutcome是字面量替换编辑editText的返回值。旧形态中replacements生产环境零读取者。单匹配策略本身予以保留——它由后端内部以FS_AMBIGUOUS_EDIT/FS_EDIT_NOT_FOUND错误码抛出强制执行错误类型词汇见 types.ts错误消息也保留了内部计数replaceAll仅被 packages/fs/tool-fs/src/edit.ts 中的formatEditOutput读取——而这只是工具本身已持有的replace_all参数的回声export function formatEditOutput(displayPath: string, replaceAll: boolean): string { return replaceAll ? The file ${displayPath} has been updated. All occurrences were successfully replaced. : The file ${displayPath} has been updated successfully. }精简后FsEditOutcome收窄为{ version, before, after }与FsWriteOutcome中真正由后端发现的字段对齐types.tsexport interface FsEditOutcome { /** Opaque version of the file after the edit. */ version: FsVersion /** The files content BEFORE the edit. */ before: string /** The files content AFTER the edit. */ after: string }请求侧的replaceAllFsEditRequest保持不变——它是消费者真正需要的入参编辑工具execute也继续将其透传给ctx.fs.editTextedit.ts。4.FileReadOutcome.limit.version渲染不需要、事件用不到FileReadOutcome位于 packages/fs/tool-fs/src/read-render.ts由读取工具填充。旧形态携带limit与version但formatReadOutput只渲染offset/lines/totalLines/truncatedByBytes——页脚里展示的一切Showing lines X-Y of Z、End of file都可以从lines/totalLines直接推导fs/observed事件发射直接使用info.version见 read.tsctx.emit(fs/observed, target, { kind: present, version: info.version }, exec)而不是 outcome 上的版本副本。因此FileReadOutcome最终保留为纯展示所需的窗口形状export interface FileReadOutcome { /** 1-based first line requested. */ offset: number /** Returned lines, already numbered. */ lines: FileTextLine[] /** Exact total line count in the file. */ totalLines: number /** Whether selected output hit the byte cap. */ truncatedByBytes?: true }决策摘要删什么、留什么本次变更的决策可归纳为一张清晰的删/留对照表表面处理理由dsh-fs-local的STREAM_MIN_SIZE/FsIoInternals.streamMinSize删除常量、其再导出与配置项全仓库零读取者真实路由常量在dsh-tool-fs的readStreamMinSizeFsTarget.inputPath删除生产环境零读取者每个后端与测试 mock 都要虚构值FsEditOutcome.replacements删除生产环境零读取者单匹配策略由后端错误码强制执行FsEditOutcome.replaceAll删除仅被formatEditOutput读取属于工具已持有参数的回声FsEditRequest.replaceAll保留请求侧入参编辑工具真正需要FsWriteOutcome/FsEditOutcome的version/before/after保留由后端发现并真正消费的字段FileReadOutcome.limit/.version删除渲染不需要事件发射直接用info.version随类型一同收窄的还有filesystem.md 中的相关粘贴、packages/fs/fs/README.md以及不得不虚构已删除字段的测试 fake——类型一变fake 与文档的虚构成本随之消失这正是接口瘦身带来的连锁收益。为什么不留着它们替代方案的取舍面向未来功能时每个被删字段似乎都能找到以后可能有用的理由但逐一审视后都被否决未来权限/隔离层需要解析前的路径来生成错误文本它需要的是请求本身而每个调用点仍然持有请求parseReadArgs等调用方手中的原始参数不需要靠FsTarget.inputPath传递。替换了 N 处可能成为面向模型的文本这是需要时再设计的行为变更且后端内部的计数已为其错误消息保留不必提前挂在 outcome 上。读取页脚可能展示limit页脚展示的一切已可从lines/totalLines推导无需冗余字段。反方成本却是确定的每个现有和未来的后端远程、原生都必须编造无人消费的协议字段每个测试 mock 都必须满足它们。用确定的当下成本去赌不确定的未来需求不划算。验证删除即证据验证方式非常直接——已删除表面不复存在dsh-fs-local中不再有STREAM_MIN_SIZE/streamMinSize当前仓库搜索该符号仅命中消费方dsh-tool-fs与决策一致FsTarget无inputPathFsEditOutcome无replacements/.replaceAllFileReadOutcome无limit/.version。同时请求侧replaceAllFsEditRequest与FsWriteOutcome/FsEditOutcome上的版本字段保持不变测试 fake 随类型一同收窄。由于formatEditOutput在两个replace_all分支中生成的文本都没有变化仍是那句 has been updated successfully. / All occurrences were successfully replaced.因此没有任何快照预期输出发生改动——行为完全兼容纯属表面清理。后果与后续后端不增加新义务反而卸下了四个无人消费的字段远程、原生等任何未来后端的协议实现负担变小测试 mock 的虚构成本归零。一个已知的文本层面重叠fs 发现功能glob/grep 工具见 tool-fs-search涉及相同的dsh-fs类型文件——这是文本而非设计层面的重叠可以机械地合并解决。从更广的视角看这次清理是 DeepSeek Harness 一系列只写表面审计中的一环同目录下还有 2026-06-20-prune-dead-seam-methods、2026-07-02-remove-stream-chunk-mirror 等相邻笔记。其方法论可以提炼为可复用的接缝卫生准则用零读取者说话一个字段若全仓库含源码与测试无人读取它就不是接口而是税。镜像事实必须消除同一配置阈值出现在后端与消费方就必然面临漂移把路由留在真正做决策的那一层。收窄类型时同步收窄文档与 fake类型是契约契约变则粘贴的文档片段与测试替身必须同批更新否则死代码会借文档复活。用快照验证零行为变化当输出文本逐字节不变时快照测试就是这次清理是纯删减的最强证明。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
