# tool_fileio **Repository Path**: vickywang1990/tool_fileio ## Basic Information - **Project Name**: tool_fileio - **Description**: 基于openAI格式的操作文件工具 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-12 - **Last Updated**: 2026-05-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # tool_fileio File I/O tool module for AgentBee. Provides 8 OpenAI-standard file operation tools that delegate to `Nervsys\Ext\libFileIO`. ## Overview `tool_fileio` is a PHP module that gives AI agents file system access capabilities through the OpenAI function-calling interface. It's designed to work within the [AgentBee](https://github.com/ ...) framework, exposing safe, sandboxed file operations as callable tools. Author: wangwenjing License: Apache-2.0 PHP: >= 8.1 ## Features - **8 OpenAI-standard tools** — conform to the OpenAI function-calling schema - **Sandbox isolation** — optional root path restriction prevents agents from operating outside a designated directory - **Large file support** — `readFile` supports offset/limit pagination for files of any size - **Idempotent deletes** — delete operations succeed even if the target doesn't exist - **libFileIO backed** — all directory operations delegate to the Nervsys `libFileIO` extension - **Configurable** — `max_read_size` and `sandbox_enabled` can be set via `module.json` ## Installation Place the module in your AgentBee modules directory: ``` AgentBee/ └── modules/ └── tool_fileio/ ├── go.php ├── tool.php └── module.json ``` ## Configuration Edit `module.json` to tune defaults: ```json { "config": { "max_read_size": 1048576, "sandbox_enabled": true } } ``` | Key | Type | Default | Description | |-----|------|---------|-------------| | `max_read_size` | int | 1048576 (1MB) | Max bytes per single `readFile` call | | `sandbox_enabled` | bool | true | Enable sandbox path restriction | ### Programmatic config ```php $tool = tool_fileio\go::new(); $tool->setRootPath('/home/agent/workspace'); $tool->setSandboxEnabled(true); $tool->max_read_size = 2097152; // 2MB ``` ## Usage ### Tool metadata (for LLM function definitions) ```php use modules\tool_fileio\tool; $tools = tool::META; // → Returns array of 8 OpenAI function definitions ``` ### Execute a tool ```php use tool_fileio\go; // Setup with sandbox $tool = go::new(); $tool->setRootPath('/home/agent/workspace'); // Read file (paginated) $result = $tool->readFile('README.md', offset: 0, limit: 8192); // → ['success' => true, 'content' => '...', 'truncated' => true/false, 'total_size' => N] // Write file $result = $tool->writeFile('notes.txt', 'Hello world'); // → ['success' => true, 'path' => 'notes.txt', 'bytes' => 11] // Append $result = $tool->writeFile('notes.txt', '\nMore text', append: true); // List directory $result = $tool->listDirectory('src'); // → ['success' => true, 'contents' => [...]] // Create directory $result = $tool->createDirectory('logs/2025'); // Delete file (idempotent) $result = $tool->deleteFile('temp.txt'); // Search files (glob) $result = $tool->searchFiles('src', '*.php', recursive: true); // → ['success' => true, 'files' => ['src/a.php', 'src/b.php', ...]] // Copy directory $result = $tool->copyDirectory('backup', 'backup_copy'); // → ['success' => true, 'copied' => 15] // Delete directory $result = $tool->deleteDirectory('temp_dir'); // → ['success' => true, 'removed' => 8] ``` ## API Reference ### readFile ``` readFile(path: string, offset?: int, limit?: int) → object ``` Read file content in bytes. For large files, use `offset` + `limit` to paginate. **Parameters** - `path` (required) — absolute or relative file path - `offset` (optional) — byte offset to start from, default 0 - `limit` (optional) — max bytes to read, default 8192, max 1048576 **Returns** ```json { "success": true, "path": "README.md", "content": "file content...", "truncated": false, "offset": 0, "limit": 8192, "total_size": 12345 } ``` When `truncated` is `true`, there is more content. Call again with `offset = previous_offset + limit` to read the next chunk. --- ### writeFile ``` writeFile(path: string, content: string, append?: bool) → object ``` Write content to a file (creates if not exists). Set `append = true` to append instead of overwrite. **Parameters** - `path` (required) — file path - `content` (required) — content string - `append` (optional) — append mode, default false --- ### listDirectory ``` listDirectory(path: string) → object ``` List directory contents. Returns an array of items with name, path, size, and type info. --- ### createDirectory ``` createDirectory(path: string) → object ``` Create a directory and all necessary parent directories. Succeeds if the directory already exists. --- ### deleteFile ``` deleteFile(path: string) → object ``` Permanently delete a file. **Idempotent** — returns success even if the file did not exist. ⚠️ **This action cannot be undone.** --- ### searchFiles ``` searchFiles(path: string, pattern: string, recursive?: bool) → object ``` Search files matching a glob pattern within a directory. **Parameters** - `path` (required) — directory to search - `pattern` (required) — glob pattern, e.g. `"*.php"`, `"*.{json,xml}"`, `"test*.js"` - `recursive` (optional) — include subdirectories, default false --- ### copyDirectory ``` copyDirectory(src: string, dst: string) → object ``` Recursively copy a directory from source to destination. ⚠️ Throws error if destination already exists. --- ### deleteDirectory ``` deleteDirectory(path: string) → object ``` Recursively delete a directory and all its contents. ⚠️ **This action cannot be undone.** --- ## Sandbox When `sandbox_enabled = true` and `root_path` is set, all file operations are restricted to within `root_path`. Attempts to access files outside this boundary return: ```json {"success": false, "error": "Path is outside the allowed root directory"} ``` To disable sandbox restriction: ```php $tool->setSandboxEnabled(false); ``` ## Error Handling All tools return a consistent error format on failure: ```json {"success": false, "error": "Human-readable error message"} ``` All tools are designed to be safe to call multiple times (`idempotent`) wherever possible. ## Repository https://gitee.com/vickywang1990/tool_fileio