跳到主要内容

文件系统与执行

Suzent 通过两种模式提供安全的文件访问和代码执行：沙箱模式（隔离的 Docker 容器）和主机模式（带限制的直接执行）。

执行模式​

模式BashTool文件工具路径风格
沙箱在 Docker 容器中运行虚拟文件系统/persistence、/shared、/mnt/*
主机在主机上运行主机文件系统$PERSISTENCE_PATH、$SHARED_PATH、$MOUNT_*

在创建对话时，可通过聊天设置面板切换沙箱模式。

虚拟文件系统（两种模式通用）​

虚拟路径映射至用途
/persistence.suzent/sandbox/sessions/{chat_id}/每个对话的独立存储
/shared.suzent/sandbox/shared/跨对话共享存储
/uploads.suzent/sandbox/sessions/{chat_id}/uploads/上传的文件
/mnt/*自定义卷主机目录

相对路径默认指向 /persistence：data.csv → /persistence/data.csv

自定义卷挂载​

# config/default.yaml
sandbox_volumes:
  - "D:/datasets:/data"
  - "D:/skills:/mnt/skills"

这样 /data/file.csv 就会映射到主机上的 D:/datasets/file.csv。

沙箱模式​

使用 Docker 容器进行隔离执行。每个聊天会话拥有独立的命名容器（suzent-sandbox-{id}），首次使用时启动并在会话期间保持运行。

特性​

  • 隔离：每个会话运行在独立容器中（默认通过 bridge 网络访问互联网）
  • 数据持久化：/persistence 和 /shared 通过绑定挂载自主机——数据在容器重启和删除后仍然保留
  • 自动恢复：容器崩溃时自动重启
  • 多语言支持：Python、Node.js（需自定义镜像）、Shell 命令
  • 资源限制：512 MB 内存、1 CPU、256 进程上限

前提条件​

  • Docker Desktop（Windows/macOS）或 Docker Engine（Linux）
  • 无需 KVM、特权模式或额外服务

配置参考​

键默认值说明
sandbox_enabledfalse启用沙箱模式
sandbox_imagepython:3.11-slim使用的 Docker 镜像
sandbox_networkbridge网络模式（bridge = 有互联网，none = 完全隔离）
sandbox_idle_timeout_minutes30闲置 N 分钟后停止容器
sandbox_volumes[]额外的绑定挂载（host:container）

主机模式​

直接在主机上执行，但有路径限制。

在主机模式下，可在 Bash 命令中使用以下环境变量：

变量指向
$PERSISTENCE_PATH会话目录
$SHARED_PATH共享目录
$MOUNT_SKILLS技能目录
$MOUNT_*其他挂载卷

文件工具​

ReadFileTool​

读取文件，支持自动格式转换（文本、PDF、DOCX、XLSX、图片 OCR）。

WriteFileTool​

创建或覆盖文件。

注意

会覆盖整个文件。小修改请使用 EditFileTool。

EditFileTool​

精确替换文件中的文本片段。

GlobTool​

按模式查找文件（如 **/*.py）。

GrepTool​

用正则表达式搜索文件内容。

安全​

所有路径均经过验证，防止目录遍历攻击：

  • ✅ /persistence/data.csv
  • ✅ /shared/model.pt
  • ✅ /data/file.txt（已挂载时）
  • ❌ /etc/passwd
  • ❌ ../../../secret
  • ❌ 项目源码目录（主机模式下）

故障排查​

问题解决方案
文件未找到检查主机上的 .suzent/sandbox/sessions/{chat_id}/
路径遍历错误确保路径在允许的目录范围内
卷无法访问检查配置中的 sandbox_volumes
容器启动失败确认 Docker Desktop 正在运行（docker ps）
找不到 Node.js构建自定义镜像：docker compose -f docker/sandbox-compose.yml build，并设置 sandbox_image: suzent-sandbox