文件写入、替换与编码

write_file 适合新文件或明确的完整覆盖；edit 适合保留其余内容的局部替换。已有文件先核对内容和 diff，避免把局部片段误当作全部文件写回。

写入与创建

write_file 接受绝对 file_path 和 content；不存在时创建文件及父目录，存在时覆盖。不要用它写原始 .ipynb JSON，Notebook 应走单元格编辑。

write_file(file_path="/workspace/app/notes.txt", content="Verified build steps\n")

写入通常展示变更并经过适用审批，实际是否自动批准取决于模式和规则。成功消息只证明该次文件操作完成，不证明内容正确或测试通过。

精确替换

edit(
  file_path="/workspace/app/src/config.ts",
  old_string="const retryLimit = 2;",
  new_string="const retryLimit = 3;",
  replace_all=false
)

old_string 是字面文本，空白与缩进也重要；默认需要唯一匹配。replace_all:true 明确替换所有匹配。old_string 为空只用于目标不存在时创建，不能用空串清空一个已有文件。

目标不存在、路径不合要求、无匹配或仍有多处歧义会失败。官方描述工具可通过模型多阶段修正匹配；这不取消用户核对最终 diff 的必要性，也不意味着模糊匹配总能成功。

已有文件编码

读取先尝试 UTF-8，再用 chardet，最后回退系统 code page。对已有文件，write_file 和 edit 尽量保留识别到的编码及 BOM；不要把“工具内部以字符串编辑”理解为自动将所有文件转换为 UTF-8。

新文件编码

{
  "general": {"defaultFileEncoding": "utf-8-bom"}
}

不设置时通常新建 UTF-8 无 BOM，并允许平台自动调整；显式 utf-8 为无 BOM 且不进行自动 BOM 调整；utf-8-bom 为新文件写 BOM。该设置不负责重新编码已有文件。

Windows 的 .bat/.cmd 自动使用 CRLF，与编码设置无关。Windows 非 UTF-8 code page 下，新 .ps1 在没有显式 defaultFileEncoding 时自动加 UTF-8 BOM，以兼容 Windows PowerShell 5.1；已有文件仍保留原编码。显式 utf-8 会关闭该自动 BOM。

失败后的处理

先确认实际文件状态，重新读目标片段，再构造更精确上下文。不要在一次失败后直接把整个文件交给 write_file 覆盖；那会把定位问题变成更大范围的修改。