文件写入器

针对大文件的安全写入策略，避免截断问题。

使用场景

• - 写入大于5000字节的文件
• 对现有文件进行重大修改
• 修改大文件的特定部分
• 之前的写入操作被截断
• 需要确保文件完整性

问题分析

文件为何会被截断

大文件写入可能因以下原因失败：

1. 1. 工具限制 - write工具每次操作可能有字节限制
2. 网络限制 - 大文件传输可能在传输过程中被截断
3. 系统限制 - OpenClaw可能对单次操作有大小限制

安全大小阈值

操作	安全大小	风险等级
write新文件	< 2000字节	✅ 安全
write新文件

2000-5000字节 | ⚠️ 中等 | | write新文件 | > 5000字节 | ❌ 高风险 | | edit修改 | < 500字节 | ✅ 安全 | | edit修改 | 500-1000字节 | ⚠️ 中等 | | edit修改 | > 1000字节 | ❌ 高风险 |

安全写入策略

第一步：读取当前状态

在进行更改之前，读取当前文件状态：

bash

读取文件以了解当前结构

read /path/to/file.md

对于大文件，读取特定部分

read /path/to/file.md --offset 100 --limit 50

目的：

• - 了解文件结构
• 确定要替换的确切文本
• 确定修改点

第二步：使用编辑工具进行精确修改

对于中小型更改，使用edit工具：

markdown
使用edit工具，包含：

• - oldText：要替换的确切文本（必须完全匹配）
• newText：替换的新文本
• file_path：文件路径

最佳实践：

• - 保持修改在500字节以内
• 精确匹配oldText（包括空白字符）
• 对大段文本使用唯一标记
• 编辑前确认oldText存在

第三步：验证结果

每次修改后，验证结果：

bash

检查文件行数

wc -l /path/to/file.md

读取修改部分

read /path/to/file.md --offset <开始位置> --limit <行数>

验证文件结尾是否正确

read /path/to/file.md --offset -10

成功标准：

• - 文件大小按预期增加
• 修改部分包含新内容
• 文件正确结尾（未被截断）
• 无语法错误（针对代码文件）

第四步：重复直至完成

对于大型多部分更新：

1. 1. 一次修改一个部分
2. 验证每次修改
3. 继续下一部分
4. 重复直至所有更改完成

备用策略

策略1：拆分大写入

如果write工具对大内容失败：

markdown
将内容拆分为块：

1. 1. 写入第一个块（头部 + 第1部分）
2. 验证并追加第2部分
3. 验证并追加第3部分
4. 继续直至完成

策略2：使用唯一标记

对于复杂修改，使用唯一标记：

markdown
在源文件中：

[现有内容]

编辑操作：
oldText: \n[现有内容]\n
newText: \n[新内容]\n

策略3：增量构建

用于创建新的大文件：

markdown

1. 1. 创建具有基本结构的文件
2. 使用edit逐个添加部分
3. 每次添加后验证
4. 最终验证

策略4：备份与恢复

用于关键文件修改：

bash

修改前创建备份

cp /path/to/file.md /path/to/file.md.backup

尝试修改

...（写入或编辑操作）

如果修改失败，恢复

cp /path/to/file.md.backup /path/to/file.md

错误恢复

编辑工具失败

症状： 在文件中找不到确切文本

原因：

• - oldText不完全匹配
• 空白字符差异（空格与制表符）
• 文件已被修改
• 文本在文件中不存在

解决方案：

1. 1. 重新读取文件以获取确切内容
2. 对大段文本使用唯一标记
3. 精确匹配空白字符（从文件读取中复制）
4. 使用更小的oldText以获得更精确的匹配

写入工具截断

症状： 文件突然结束或不完整

解决方案：

1. 1. 使用edit工具代替write
2. 将内容拆分为更小的块
3. 增量写入（逐部分进行）
4. 每次操作后验证文件大小

文件损坏

症状： 文件有语法错误或无效内容

解决方案：

1. 1. 从备份恢复
2. 重新读取并重新验证
3. 使用增量构建策略
4. 每次修改后验证语法

示例

示例1：向大文件添加部分

markdown
步骤1：读取文件以找到插入点
read /path/to/large-file.md --offset 50 --limit 10

步骤2：使用edit添加新部分
edit:
file_path: /path/to/large-file.md
oldText: ## 现有部分\n\n此处内容
newText: ## 现有部分\n\n此处内容\n\n## 新部分\n\n新内容

步骤3：验证
read /path/to/large-file.md --offset 50 --limit 20

示例2：创建新的大文件

markdown
步骤1：创建基本结构
write:
file_path: /path/to/new-file.md
content: # 标题\n\n## 第1部分\n\n内容1

步骤2：增量添加部分
edit:
file_path: /path/to/new-file.md
oldText: 内容1
newText: 内容1\n\n## 第2部分\n\n内容2

步骤3：验证
wc -l /path/to/new-file.md

示例3：替换大段内容

markdown
步骤1：读取文件以找到确切文本
read /path/to/file.md

步骤2：使用唯一标记
edit:
file_path: /path/to/file.md
oldText: \n[旧内容]\n
newText: \n[新内容]\n

步骤3：验证
read /path/to/file.md | grep 新内容

最佳实践

1. 1. 编辑前始终读取 - 了解当前状态
2. 使用edit进行修改 - 比write更精确
3. 保持更改小 - 每次编辑不超过500字节
4. 每次操作后验证 - 不要批量操作
5. 使用唯一标记 - 用于复杂修改
6. 创建备份 - 用于关键文件
7. 优雅处理错误 - 提供恢复策略
8. 增量测试 - 验证每一步

决策树

需要写入/更新文件？
├─ 新文件？
│ ├─ < 2000字节？
│ │ └─ 使用write工具
│ └─ > 2000字节？
│ └─ 使用增量构建策略
└─ 现有文件？
├─ 小更改（< 500字节）？
│ └─ 使用edit工具
├─ 中等更改（500-1000字节）？
│ └─ 使用带唯一标记的edit
└─ 大更改（> 1000字节）？
└─ 使用增量编辑策略

快速参考

任务	工具	策略
创建小文件	write	直接写入
创建大文件

write + edit | 增量构建 | | 小修改 | edit | 直接编辑 | | 中等修改 | edit | 带标记编辑 | | 大修改 | edit | 增量编辑 | | 替换部分 | edit | 唯一标记 | | 追加内容 | edit | 编辑文件结尾 |