file-writer
# File Writer
Safe file writing strategy for large files to avoid truncation issues.
## When to Use
- Writing files larger than 5000 bytes
- Updating existing files with significant changes
- Modifying specific sections of large files
- Previous write operations were truncated
- Need to ensure file integrity
## Problem Analysis
### Why Files Get Truncated
Large file writes can fail due to:
1. **Tool limitations** - `write` tool may have byte limits per operation
2. **Network limits** - Large file transfers may be truncated during transmission
3. **System limits** - OpenClaw may have size limits on single operations
### Safe Size Thresholds
| Operation | Safe Size | Risk Level |
|-----------|------------|-------------|
| `write` new file | < 2000 bytes | ✅ Safe |
| `write` new file | 2000-5000 bytes | ⚠️ Moderate |
| `write` new file | > 5000 bytes | ❌ High risk |
| `edit` modification | < 500 bytes | ✅ Safe |
| `edit` modification | 500-1000 bytes | ⚠️ Moderate |
| `edit` modification | > 1000 bytes | ❌ High risk |
## Safe Writing Strategy
### Step 1: Read Current State
Before making changes, read the current file state:
```bash
# Read the file to understand current structure
read /path/to/file.md
# For large files, read specific sections
read /path/to/file.md --offset 100 --limit 50
```
**Purpose:**
- Understand file structure
- Identify exact text to replace
`- Determine modification points
### Step 2: Use Edit Tool for Precise Modifications
For small to medium changes, use `edit` tool:
```markdown
Use `edit` tool with:
- `oldText`: Exact text to replace (must match exactly)
- `newText`: New text to replace with
- `file_path`: Path to the file
```
**Best Practices:**
- Keep modifications under 500 bytes
- Match `oldText` exactly (including whitespace)
- Use unique text markers for large sections
- Verify `oldText` exists before editing
### Step 3: Verify Results
After each modification, verify the result:
```bash
# Check file line count
wc -l /path/to/file.md
# Read modified section
read /path/to/file.md --offset <start> --limit <lines>
# Verify file ends correctly
read /path/to/file.md --offset -10
```
**Success Criteria:**
- File size increased as expected
- Modified section contains new content
- File ends correctly (not truncated)
- No syntax errors (for code files)
### Step 4: Repeat Until Complete
For large multi-section updates:
1. Modify one section at a time
2. Verify each modification
3. Proceed to next section
4. Repeat until all changes complete
## Fallback Strategies
### Strategy 1: Split Large Writes
If `write` tool fails for large content:
```markdown
Split content into chunks:
1. Write first chunk (header + section 1)
2. Verify and append section 2
3. Verify and append section 3
4. Continue until complete
```
### Strategy 2: Use Unique Markers
For complex modifications, use unique markers:
```markdown
In source file:
<!-- SECTION_START: configuration -->
[existing content]
<!-- SECTION_END: configuration -->
Edit operation:
oldText: "<!-- SECTION_START: configuration -->\n[existing content]\n<!-- SECTION_END: configuration -->"
newText: "<!-- SECTION_START: configuration -->\n[new content]\n<!-- SECTION_END: configuration -->"
```
### Strategy 3: Incremental Build
For creating new large files:
```markdown
1. Create file with basic structure
2. Add sections one by one using edit
3. Verify after each addition
4. Final verification
```
### Strategy 4: Backup and Restore
For critical file modifications:
```bash
# Create backup before modification
cp /path/to/file.md /path/to/file.md.backup
# Attempt modification
# ... (write or edit operation)
# If modification fails, restore
cp /path/to/file.md.backup /path/to/file.md
```
## Error Recovery
### Edit Tool Fails
**Symptom:** "Could not find exact text in file"
**Causes:**
- `oldText` doesn't match exactly
- Whitespace differences (spaces vs tabs)
- File already modified
- Text doesn't exist in file
**Solutions:**
1. **Re-read the file** to get exact content
2. **Use unique markers** for large sections
3. **Match whitespace exactly** (copy from file read)
4. **Use smaller `oldText`** for more precise matching
### Write Tool Truncates
**Symptom:** File ends abruptly or is incomplete
**Solutions:**
1. **Use edit tool** instead of write
2. **Split content** into smaller chunks
3. **Write incrementally** (section by section)
4. **Verify file size** after each operation
### File Corruption
**Symptom:** File has syntax errors or invalid content
**Solutions:**
1. **Restore from backup**
2. **Re-read and re-verify**
3. **Use incremental build** strategy
4. **Validate syntax** after each modification
## Examples
### Example 1: Adding Section to Large File
```markdown
Step 1: Read file to find insertion point
read /path/to/large-file.md --offset 50 --limit 10
Step 2: Use edit to add new section
edit:
file_path: /path/to/large-file.md
oldText: "## Existing Section\n\nContent here"
newText: "## Existing Section\n\nContent here\n\n## New Section\n\nNew content"
Step 3: Verify
read /path/to/large-file.md --offset 50 --limit 20
```
### Example 2: Creating Large New File
```markdown
Step 1: Create basic structure
write:
file_path: /path/to/new-file.md
content: "# Title\n\n## Section 1\n\nContent 1"
Step 2: Add sections incrementally
edit:
file_path: /path/to/new-file.md
oldText: "Content 1"
newText: "Content 1\n\n## Section 2\n\nContent 2"
Step 3: Verify
wc -l /path/to/new-file.md
```
### Example 3: Replacing Large Section
```markdown
Step 1: Read file to find exact text
read /path/to/file.md
Step 2: Use unique markers
edit:
file_path: /path/to/file.md
oldText: "<!-- START: old-section -->\n[old content]\n<!-- END: old-section -->"
newText: "<!-- START: old-section -->\n[new content]\n<!-- END: old-section -->"
Step 3: Verify
read /path/to/file.md | grep "new content"
```
## Best Practices
1. **Always read before editing** - Understand current state
2. **Use edit for modifications** - More precise than write
3. **Keep changes small** - Under 500 bytes per edit
4. **Verify after each operation** - Don't batch operations
5. **Use unique markers** - For complex modifications
6. **Create backups** - For critical files
7. **Handle errors gracefully** - Provide recovery strategies
8. **Test incrementally** - Verify each step
## Decision Tree
```
Need to write/update file?
├─ New file?
│ ├─ < 2000 bytes?
│ │ └─ Use write tool
│ └─ > 2000 bytes?
│ └─ Use incremental build strategy
└─ Existing file?
├─ Small change (< 500 bytes)?
│ └─ Use edit tool
├─ Medium change (500-1000 bytes)?
│ └─ Use edit with unique markers
└─ Large change (> 1000 bytes)?
└─ Use incremental edit strategy
```
## Quick Reference
| Task | Tool | Strategy |
|------|------|----------|
| Create small file | write | Direct write |
| Create large file | write + edit | Incremental build |
| Small modification | edit | Direct edit |
| Medium modification | edit | Edit with markers |
| Large modification | edit | Incremental edit |
| Replace section | edit | Unique markers |
| Append content | edit | Edit end of file |
标签
skill
ai
