[Bug Report] edit（str_replace_editor）重写文件时静默剥掉 UTF-8 BOM

[DRAG0NM]

摘要

str_replace_editor 工具的 str_replace / insert 会静默剥掉 UTF-8 BOM：读路径 readText 用 TextDecoder("utf-8", { fatal: true }) 解码（默认剥离 BOM），编辑后 writeText 把无 BOM 的内容写回——带 BOM 的文件被编辑一次后 BOM 永久丢失。依赖 BOM 识别编码的工具（记事本、旧版 PowerShell、部分解析器）对处理后的文件可能误判编码。

复现步骤

1. 创建一个带 UTF-8 BOM 的文件（开头 EF BB BF），例如用记事本"另存为 UTF-8"保存一个脚本文件。
2. 在会话中调用 str_replace_editor 的 str_replace（或 insert）修改该文件。
3. 用十六进制查看文件头：EF BB BF 已消失（BOM 被剥掉）。
4. 再次读取文件内容确认修改成功但 BOM 永久丢失（原 BOM 字节无法恢复）。

逻辑复现，机制已实证（见验证材料）。

根因（源码定位，rc.6）

1. 编辑路径是"解码-重写" — @deepseek-ai/dsh-tool-str-replace-editor/lib/index.js：

   • L164（str_replace）：const before = await ctx.fs.readText(target, exec.signal); → L171：ctx.fs.writeText(target, before.slice(0, offset) + newValue + before.slice(...))；
   • L195（insert）：const lines = (await ctx.fs.readText(target, exec.signal)).split("\n") → L211 ctx.fs.writeText(target, after, ...) —— 两个命令都以"解码后的文本"为基准写回，BOM 一旦在解码层被剥就永远回不去。

2. 解码层默认剥 BOM — @deepseek-ai/dsh-fs-local/lib/index.js：

   • L313-321 decodeUtf8：new TextDecoder("utf-8", { fatal: true }).decode(buffer) —— TextDecoder 默认 ignoreBOM: false，解码时剥离 BOM（不产生 \uFEFF 字符）；
   • L351-357 readWholeText → 该解码；L779-797 writeText 直接写回字符串内容，无任何 BOM 恢复逻辑。

3. 实证（本机 Node 复刻同款解码）：

   • TextDecoder("utf-8",{fatal:true}) 解码 EF BB BF 前缀文件 → 文本不含 \uFEFF（BOM 被剥）；
   • 同参数加 ignoreBOM: true → \uFEFF 保留；
   • 编辑后写回：文件头不再是 EF BB BF —— BOM 永久丢失。

建议修复

方案 A（推荐）· 解码保留 BOM 字符：decodeUtf8 改用 new TextDecoder("utf-8", { fatal: true, ignoreBOM: true })——BOM 作为 \uFEFF 字符进入文本流，编辑后原样写回（BOM 被当作内容的一部分保留）。一行级改动；代价是模型可见文本首字符为 \uFEFF（渲染层通常不可见，可接受）。

方案 B · 写回时按原文恢复 BOM：readText 记录原文件是否带 BOM（或由 fs 层在 edit/write 时检测原文头字节），writeText 在原文带 BOM 且新内容不带时前置 BOM。模型侧文本保持干净（无 \uFEFF），改动稍大（需在 fs 层透传标志）。

方案 C · 字节级编辑：编辑路径基于 readBytes 的字节偏移而非解码文本（BOM 是前 3 字节，天然保留）。改动最大，但对编码敏感文件最稳妥（顺带覆盖非 UTF-8 场景）。

影响

• 任何带 UTF-8 BOM 的文件被 edit 工具修改后 BOM 静默丢失——文件字节级内容被改变，可能影响依赖 BOM 判定的下游工具（Windows 记事本/旧 PowerShell/部分脚本解释器按 BOM 选编码）；
• 对 GBK 等其他编码文件（若被误当 UTF-8 解码），BOM 丢失叠加编码歧义，风险更高；
• 编辑工具是 Agent 高频操作，BOM 类文件的用户几乎必然踩中。

环境

• 源码定位：0.1.0-rc.6（npx 缓存安装包，Node v24.16.0，Windows 11）
• 原报告：edit 工具重写文件时会剥掉 BOM #1022

验证材料

• 本机实证：同款 TextDecoder 参数（fatal:true）解码 BOM 文件 → BOM 被剥；ignoreBOM:true → 保留；编辑写回后文件头不再为 EF BB BF；
• rc.6 源码逐行核对：dsh-fs-local/lib/index.js L313-321/L351-357/L779-797 与 dsh-tool-str-replace-editor/lib/index.js L164/L171/L195/L211。

---

First analysis of discussion #1022. Happy to open a PR with fix option A.