write_to_file

write_to_file工具用于创建新文件或完全替换现有文件内容，并提供交互式审批流程。它会在应用更改前显示差异视图供用户审查。

参数

工具接受以下参数：

参数名	类型	必填	说明	示例
`path`	string	是	要写入的文件路径，相对于当前工作目录。支持自动创建目录结构	`config/settings.json`
`content`	string	是	要写入文件的完整内容。必须包含文件所有部分，禁止使用占位符	`{ "key": "value" }`
`line_count`	number	是	文件总行数(包括空行)，用于验证内容完整性。必须与实际内容行数匹配	`14`

功能说明

该工具将内容写入指定文件，如果文件不存在则创建新文件，如果文件已存在则完全覆盖其内容。所有更改都需要通过差异视图界面进行显式用户审批，用户可以在应用更改前审查甚至编辑提议的内容。

使用场景

当Roo需要从头创建新文件时
当Roo需要完全重写现有文件时
当为新项目创建多个文件时
当生成配置文件、文档或源代码时
当需要在应用更改前进行审查时

主要特性

交互式审批：在差异视图中显示更改，需要显式批准才能应用
用户编辑支持：允许在最终批准前编辑提议的内容
安全措施：检测代码遗漏、验证路径并防止内容截断
编辑器集成：自动滚动到第一个差异处打开差异视图
内容预处理：处理不同AI模型的产物以确保内容干净
访问控制：在更改前验证.rooignore限制
父目录处理：可能通过系统依赖处理目录创建
完全替换：在单个操作中提供完全转换的文件

限制

不适合现有文件：对于修改现有文件比apply_diff慢且效率低
大文件性能：文件越大操作越慢
完全覆盖：替换整个文件内容，无法保留原始内容
需要行数：需要准确的行数以检测潜在内容截断
审查开销：审批流程比直接编辑多出额外步骤
仅限交互：不能在需要非交互执行的自动化工作流中使用

工作原理

当调用write_to_file工具时，它遵循以下流程：

参数验证：验证必需参数和权限
- 检查是否提供了path、content和line_count
- 如果line_count缺失/无效，则恢复任何差异视图更改并返回错误，如果是修改现有文件则建议替代工具(apply_diff、insert_content等)
- 验证文件是否被允许(不受.rooignore限制)
- 确保路径在工作区范围内
- 跟踪缺失参数的连续错误计数
- 为每个验证失败显示特定错误消息
内容预处理：
- 移除AI模型可能添加的代码块标记
- 处理转义的HTML实体(特别是非Claude模型)
- 如果内容中意外包含行号则去除
- 为不同的AI提供者执行模型特定处理
差异视图生成：
- 在编辑器中打开显示提议更改的差异视图
- 添加300ms延迟以确保UI响应
- 自动滚动到第一个差异处
- 高亮显示更改以便审查
用户审批流程：
- 等待显式用户批准继续
- 允许用户在差异视图中编辑内容
- 捕获任何用户编辑以获取最终内容
- 提供完全拒绝更改的选项
- 检测并合并用户修改到最终结果中
安全验证：
- 通过与提供的行数比较检测潜在内容截断
- 如果内容看起来不完整则显示警告
- 验证文件路径和访问权限
- 特别检查isOutsideWorkspace标志是否文件在工作区外
文件写入：
- 将批准的内容(含任何用户编辑)写入文件
- 提供成功写入的确认
- 成功时重置连续错误计数器

使用示例

创建新项目时，Roo生成多个文件但让您在提交更改前审查每个文件
设置配置文件时，Roo在差异视图中显示提议的配置供审批
生成文档时，Roo创建markdown文件但让您在差异视图中进行最终调整
开发原型时，Roo在差异视图中显示完整的源文件，您可以在保存前进行微调

用法示例

创建新的JSON配置文件：

<write_to_file>
<path>config/settings.json</path>
<content>
{
  "apiEndpoint": "https://api.example.com",
  "theme": {
    "primaryColor": "#007bff",
    "secondaryColor": "#6c757d",
    "fontFamily": "Arial, sans-serif"
  },
  "features": {
    "darkMode": true,
    "notifications": true,
    "analytics": false
  },
  "version": "1.0.0"
}

参数​

功能说明​

使用场景​

主要特性​

限制​

工作原理​

使用示例​

用法示例​

参数