write_file - 写入文件

概述

write_file 工具用于将内容写入本地文件系统中的指定文件。支持创建新文件或覆盖现有文件。

工具名称

• 内部名称: write_file
• 显示名称: WriteFile
• 图标: 铅笔 (Pencil)

参数

必需参数

参数名	类型	说明
file_path	string	要写入的文件的绝对路径（例如：/home/user/project/file.txt）。不支持相对路径。
content	string	要写入文件的内容。

可选参数

参数名	类型	说明
modified_by_user	boolean	内容是否由用户修改过。用于内部跟踪。

功能说明

1. 文件操作：

   • 创建新文件
   • 覆盖现有文件
   • 自动创建必要的父目录

2. 用户确认：

   • 在写入前会显示差异预览
   • 用户可以在确认对话框中修改内容
   • 支持 VSCode IDE 集成的差异视图

3. 安全限制：

   • 文件路径必须是绝对路径
   • 文件必须在项目根目录内
   • 不能写入目录

4. 内容修正：

   • 自动修正常见的格式问题
   • 规范化行尾符
   • 确保内容完整性

最佳实践

1. 对于现有文件：使用 read_file 先验证当前内容再覆盖
2. 对于大文件：考虑使用 replace 工具进行针对性编辑
3. 避免 token 限制：如果内容非常大，考虑分割成多个操作

使用示例

创建新文件

{
  "file_path": "/home/user/project/src/new-file.ts",
  "content": "export const greeting = 'Hello, World!';\n"
}

覆盖现有文件

{
  "file_path": "/home/user/project/README.md",
  "content": "# My Project\n\nThis is an updated README.\n"
}

写入配置文件

{
  "file_path": "/home/user/project/config.json",
  "content": "{\n  \"version\": \"1.0.0\",\n  \"name\": \"my-app\"\n}\n"
}

返回结果

工具返回一个包含以下字段的对象：

• llmContent: 操作结果描述
• returnDisplay: 用户友好的显示信息（包含文件差异）
• summary: 操作摘要

错误处理

可能的错误情况：

1. 路径错误：

   • 路径不是绝对路径
   • 路径不在项目根目录内
   • 路径是目录而不是文件

2. 文件访问错误：

   • 没有写入权限
   • 磁盘空间不足
   • 父目录不存在且无法创建

3. 参数错误：

   • 缺少必需参数
   • 参数类型不正确
   • 内容被截断（超过 token 限制）

用户交互

确认对话框

在 AUTO_EDIT 模式之外，工具会显示确认对话框：

• 标题: 显示文件名和操作类型（新建/修改）
• 差异视图: 显示原内容和新内容的对比
• 选项:
  • 允许一次 (Proceed Once)
  • 总是允许 (Proceed Always)
  • 在编辑器中修改 (Modify with Editor)
  • 取消 (Cancel)

VSCode 集成

在 VSCode IDE 模式下：

• 自动打开差异视图
• 支持内联编辑
• 实时预览更改

注意事项

1. 数据丢失风险：覆盖文件会永久删除原内容，建议先备份
2. 内容大小：非常大的内容可能超过 token 限制，考虑分割操作
3. 行尾符：工具会自动规范化行尾符为 LF (\n)
4. 编码：默认使用 UTF-8 编码

相关工具

• read_file: 读取文件
• replace: 替换文件中的特定文本
• list_directory: 列出目录内容
• glob: 查找文件