109 lines
3.7 KiB
Markdown
109 lines
3.7 KiB
Markdown
# File Operation Skills
|
|
|
|
Skill-level file operation tools provide safe, enhanced file system
|
|
operations for agents. All tools enforce path traversal guards, binary
|
|
file detection, and atomic writes.
|
|
|
|
## Tools
|
|
|
|
| Tool | Capability | Description |
|
|
|--------------------|-------------|--------------------------------------------------|
|
|
| `skill/file-read` | `read_only` | Read file with binary detection and size limits |
|
|
| `skill/file-write` | `writes` | Write file atomically with newline normalization |
|
|
| `skill/file-edit` | `writes` | Edit file with permission preservation |
|
|
| `skill/file-delete`| `writes` | Delete file with existence check |
|
|
|
|
## ReadFile
|
|
|
|
Reads file content with the following safety features:
|
|
|
|
- **Binary detection**: Rejects files identified as binary (PNG, ELF,
|
|
ZIP, etc.) with an explicit error message.
|
|
- **Size limits**: Files exceeding 10 MB are rejected.
|
|
- **UTF-8 normalization**: Content is decoded with the requested
|
|
encoding and normalized to valid UTF-8.
|
|
- **Line offset/limit**: Supports reading a specific range of lines.
|
|
|
|
### Example
|
|
|
|
```python
|
|
from cleveragents.skills.builtins.file_ops import register_skill_file_tools
|
|
from cleveragents.tool.registry import ToolRegistry
|
|
from cleveragents.tool.runner import ToolRunner
|
|
|
|
registry = ToolRegistry()
|
|
register_skill_file_tools(registry)
|
|
runner = ToolRunner(registry)
|
|
|
|
result = runner.execute("skill/file-read", {
|
|
"path": "src/main.py",
|
|
"sandbox_root": "/project",
|
|
})
|
|
print(result.output["content"])
|
|
```
|
|
|
|
### Error Cases
|
|
|
|
| Condition | Error Message |
|
|
|----------------------|--------------------------------------------------|
|
|
| Binary file | `Binary file detected: 'path'` |
|
|
| File too large | `File too large: N bytes exceeds limit` |
|
|
| File not found | `File not found: 'path'` |
|
|
| Path traversal | `Path traversal detected: 'path' escapes ...` |
|
|
| Not a regular file | `Not a regular file: 'path'` |
|
|
|
|
## WriteFile
|
|
|
|
Writes content to a file using atomic operations:
|
|
|
|
1. Content is written to a temporary file in the same directory.
|
|
2. The temporary file is renamed to the target path using `os.replace`.
|
|
3. If any error occurs, the temporary file is cleaned up.
|
|
|
|
### Newline Normalization
|
|
|
|
The `newline_mode` parameter controls line ending conversion:
|
|
|
|
- `"preserve"` (default): No conversion.
|
|
- `"lf"`: Convert all line endings to `\n`.
|
|
- `"crlf"`: Convert all line endings to `\r\n`.
|
|
|
|
## EditFile
|
|
|
|
Edits files using string replacement with:
|
|
|
|
- **Atomic writes**: Same temp-file-then-rename strategy as WriteFile.
|
|
- **Permission preservation**: Original file permissions are restored.
|
|
- **Single or all replacements**: Controlled by `replace_all` flag.
|
|
|
|
## DeleteFile
|
|
|
|
Deletes a file with:
|
|
|
|
- **Existence check**: Returns `existed: false` for missing files.
|
|
- **Type check**: Rejects directory targets.
|
|
- **Path traversal guard**: Same as all other tools.
|
|
|
|
## Path Traversal Guards
|
|
|
|
All tools reject paths that would escape the sandbox root:
|
|
|
|
- Paths containing `..` segments that resolve outside the sandbox.
|
|
- Absolute paths that fall outside the sandbox directory.
|
|
|
|
The rejected path is included in the error message for diagnostics.
|
|
|
|
## File Size Limits
|
|
|
|
ReadFile enforces a 10 MB content size limit. Files exceeding this
|
|
limit produce an explicit error rather than consuming excessive memory.
|
|
|
|
## Binary File Detection
|
|
|
|
ReadFile detects binary files by:
|
|
|
|
1. Checking for known binary file signatures (PNG, GIF, JPEG, ZIP,
|
|
ELF, MZ/PE, gzip).
|
|
2. Heuristic: if more than 10% of the first 8192 bytes are non-text
|
|
control characters, the file is classified as binary.
|