> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# File Tools

<Tip>
  **PRO**

  This feature is supported in the **Professional Edition**.
</Tip>

XpertAI's agent system includes a powerful **File Tools Collection**, providing AI with programmable file operations in a virtual workspace, enabling agents to **read, create, edit, rewrite, delete, and list** workspace files during execution.

These tools are integrated into the execution flow of digital expert agents, supporting workspaces tied to sessions/projects. They call backend file services through a unified interface, ensuring operations are both immediately visible and persistently stored.

## 📦 Tools Overview

| Tool Name           | Function Description                     |
| ------------------- | ---------------------------------------- |
| `list_files`        | Lists all files in the current workspace |
| `create_file`       | Creates a new file with initial content  |
| `str_replace`       | Replaces a unique string in a file       |
| `full_file_rewrite` | Overwrites file content entirely         |
| `delete_file`       | Deletes a file at the specified path     |
| `read_file`         | Reads the content of a specified file    |

## 🧰 Function Details

### 🔍 `list_files`

Lists all files in the current session or project workspace, returning a list with file paths, URLs, and basic metadata.

* **Path Description**: Relative to the `/workspace` root directory (e.g., `src/main.py`).
* **Output**: JSON list containing `filePath` and accessible `url`.
* **Use Cases**: Browsing the AI workspace file structure, confirming existing filenames, etc.

***

### 📝 `create_file`

Creates a new file and writes initial content.

* **Parameters**:
  * `file_path`: Relative file path from `/workspace` root (e.g., `src/main.py`)
  * `file_contents`: Initial file content
  * `file_description` (optional): File purpose description
  * `permissions` (optional): Octal permissions (defaults to `644`)

* **Use Cases**:
  * Initializing programming or configuration files
  * Generating code drafts for further modification

***

### 🔁 `str_replace`

Replaces a unique string in a specified file with new content.

* **Parameters**:
  * `file_path`: Target file path relative to `/workspace` root (e.g., `src/main.py`)
  * `old_str`: Original text to be replaced (must appear exactly once)
  * `new_str`: Replacement text content

* **Restriction**: For accuracy, `old_str` **must appear exactly once**; otherwise, an error is returned.

* **Use Cases**:
  * Precisely replacing variable names, function names, or configuration items
  * Correcting spelling or logical errors

***

### 🧹 `full_file_rewrite`

Completely overwrites a file's content with new content, suitable for structural or bulk modifications.

* **Parameters**:
  * `file_path`: Target file path relative to `/workspace` root (e.g., `src/main.py`)
  * `file_contents`: New content to overwrite
  * `permissions` (optional): Octal permissions (defaults to `644`)

* **Use Cases**:
  * Large-scale file updates
  * Rewriting entire documents or code based on AI output

***

### 🗑️ `delete_file`

Deletes a file at the specified path and synchronizes database record removal.

* **Parameters**:
  * `file_path`: Relative path of the file to delete from `/workspace` root (e.g., `src/main.py`)

* **Use Cases**:
  * Cleaning up unused files
  * Removing erroneous or redundant generated results

***

### 📖 `read_file`

Reads the current content of a file in the workspace.

* **Use Cases**:
  * AI retrieves context before analyzing or modifying a file
  * Users review current content before deciding on actions

***

## ⚙️ Operational Mechanism

* All file operations are performed within the agent's dedicated **Sandbox Workspace**, ensuring safe isolation.
* Each workspace is tied to a session or project.
* The file service relies on the `sandbox.fs` module, managing files through standardized interfaces.

***

## 🔗 Typical Use Cases

* **AI Code Generation**: Creating and iteratively modifying `.py`, `.js`, or other source code files
* **Collaborative Document Writing**: Gradually generating and adjusting `.md` files
* **Data Processing Tasks**: Reading or replacing fields/rows in `.csv` files
* **Project Auto-Configuration**: Batch-generating configuration files with replace/rewrite operations

***

## ✅ Usage Recommendations

* Use `list_files` and `read_file` to gather context and avoid path or content errors.
* Use `str_replace` for precise modifications and `full_file_rewrite` for major changes or refactoring.
* Ensure all paths are relative to `/workspace` and avoid absolute paths or parent directory references (e.g., `../`).

***

## 🔐 Security and Permissions

* File operation permissions default to `0644`, with optional custom permissions.
* All AI operations are logged, supporting frontend display and auditing.
* Version persistence and file recovery mechanisms are supported.