文件工具

PRO

此功能在专业版中支持。

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 操作均记录事件，支持前端回显与审计。
支持版本持久化与文件恢复机制。

📦 工具集总览​

🧰 功能详解​

🔍 list_files​

📝 create_file​

🔁 str_replace​

🧹 full_file_rewrite​

🗑️ delete_file​

📖 read_file​

⚙️ 工作机制说明​

🔗 典型使用场景​

✅ 使用建议​

🔐 安全与权限​