> ## 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.

# 文件工具

<Tip>
  **PRO**

  此功能在**专业版**中支持。
</Tip>

XpertAI 的智能体系统内置了强大的 **文件工具集**，为 AI 提供了可编程的虚拟工作区文件操作能力，帮助智能体在运行过程中 **读取、创建、编辑、重写、删除和列出**工作区文件。

这些工具集成于数字专家的智能体执行流中，支持与会话/项目绑定的工作区，通过统一接口调用后端文件服务，确保操作既即时可见，又可持久化。

## 📦 工具集总览

| 工具名称                | 功能简介           |
| ------------------- | -------------- |
| `list_files`        | 列出当前工作区内的所有文件  |
| `create_file`       | 创建一个新文件并写入初始内容 |
| `str_replace`       | 在文件中唯一替换指定字符串  |
| `full_file_rewrite` | 用新内容完全覆盖已有文件内容 |
| `delete_file`       | 删除指定路径的文件      |
| `read_file`         | 读取指定路径文件的内容    |

## 🧰 功能详解

### 🔍 `list_files`

列出当前会话或项目工作区中的所有文件，返回包含文件路径、URL 和基本元信息的列表。

* **路径说明**：相对于 `/workspace` 根目录（如 `src/main.py`）。
* **输出**：包含 `filePath` 和可访问 `url` 的 JSON 列表。
* **适用场景**：浏览当前 AI 工作区文件结构、确认已有文件名等。

***

### 📝 `create_file`

创建一个新文件并写入初始内容。

* **参数说明**：

  * `file_path`：文件相对路径，相对于 `/workspace` 根目录（如 `src/main.py`）
  * `file_contents`：文件初始内容
  * `file_description`（可选）：文件用途说明
  * `permissions`（可选）：八进制权限（默认为 `644`）

* **适用场景**：

  * 初始化编程文件、配置文件
  * 生成代码草稿供进一步修改

***

### 🔁 `str_replace`

在指定文件中将唯一字符串替换为新内容。

* **参数说明**：

  * `file_path`：目标文件路径，相对于 `/workspace` 根目录（如 `src/main.py`）
  * `old_str`：需被替换的原始文本（要求只出现一次）
  * `new_str`：替换后的文本内容

* **限制**：为保证精确性，`old_str` **必须唯一出现一次**，否则将返回提示错误。

* **适用场景**：

  * 精确替换变量名、函数名、配置项等
  * 改正拼写或逻辑错误

***

### 🧹 `full_file_rewrite`

完全用新的内容覆盖已有文件内容，适合结构性或批量修改。

* **参数说明**：

  * `file_path`：目标文件路径，相对于 `/workspace` 根目录（如 `src/main.py`）
  * `file_contents`：重写内容
  * `permissions`（可选）：八进制权限（默认为 `644`）

* **适用场景**：

  * 大规模更新文件
  * 根据 AI 输出重写整份文档或代码

***

### 🗑️ `delete_file`

删除指定路径的文件，并同步清除数据库记录。

* **参数说明**：

  * `file_path`：需删除的文件相对路径，相对于 `/workspace` 根目录（如 `src/main.py`）

* **适用场景**：

  * 清理无用文件
  * 删除错误或冗余生成的结果

***

### 📖 `read_file`

读取工作区中文件的当前内容。

* **适用场景**：

  * AI 在分析或修改文件前先获取上下文
  * 用户想查看当前内容再决定操作

***

## ⚙️ 工作机制说明

* 所有文件操作均在智能体专属的 **Sandbox 工作区** 内完成，确保操作安全隔离。
* 每个工作区与会话或项目绑定。
* 文件服务底层依赖于 `sandbox.fs` 模块，通过标准化的接口进行文件管理。

***

## 🔗 典型使用场景

* AI 代码生成：创建并反复修改 `.py`, `.js` 等源代码文件
* 文档撰写协作：逐步生成并调整 `.md` 文件
* 数据处理任务：读取、替换 `.csv` 文件中的字段或行
* 项目自动配置：批量生成配置文件并执行替换/重写操作

***

## ✅ 使用建议

* 使用 `list_files` 和 `read_file` 获取上下文，避免路径和内容错误。
* `str_replace` 更适合精确修改，`full_file_rewrite` 则适用于大改或重构。
* 所有路径请确保相对 `/workspace`，不要包含绝对路径或越级（如 `../`）。

***

## 🔐 安全与权限

* 文件操作权限默认遵循 `0644` 规则，可选传入自定义权限。
* 所有 AI 操作均记录事件，支持前端回显与审计。
* 支持版本持久化与文件恢复机制。