| name | docker-tool-specification |
| description | Docker container使用规范。当需要执行命令、操作文件、运行代码或进行任何可能受环境影响的任务时，必须使用container而非直接操作本地环境。明确沙盒隔离边界、与本地工具的交互规范、 文件路径约定以及多工具协作流程。执行命令、文件操作、代码执行时使用，或者任何应在隔离的 Docker container中运行的环境依赖任务. docker命令的工具以container为前缀，后续提及的工具名默认带上container前缀
|
Docker沙盒工具使用规范
概述
Docker沙盒是一个完全隔离的执行环境，与本地主机环境相互独立。所有涉及命令执行、文件操作、代码运行等任务，必须通过 docker 沙盒工具 进行，禁止直接操作本地环境。
核心原则
1. 强制使用沙盒
- 执行任何 shell 命令 → 使用
executeCommand 或 executeBackgroundCommand
- 创建/读取/修改/删除文件 → 使用
createFile / readFile / strReplace / fullFileRewrite / deleteFile
- 文件列表查看 → 使用
listFiles
- 下载资源 → 使用
downloadResource
- 安装软件包 → 使用
installPackage
- 查看系统信息 → 使用
getSystemInfo
2. 环境隔离边界（关键）
沙盒内部无法直接访问本地主机的：
- 文件系统路径（如
D:\、/home/user/ 等本地路径在沙盒中不存在）
- 本地已安装的软件、环境变量、配置文件
- 本地网络服务（除非通过端口映射，但不应依赖）
- 本地数据库、缓存、消息队列等服务
沙盒内部的环境特点：
- 独立的 Linux 文件系统，工作目录默认为
/workspace
- 每次
executeCommand 调用都在全新的 shell 进程中执行
- 环境变量和目录变更不会在调用之间持久化
- 沙盒中生成的文件默认只在沙盒内可用
文件路径规范
沙盒内路径
- 所有文件操作的路径参数均为相对于工作区的相对路径
- 默认工作区：
/workspace
- 正确示例：
data/input.txt、scripts/run.sh、output/result.json
- 错误示例：
D:\data\input.txt、/home/user/file.txt（这些是本地路径，沙盒中不存在）
本地与沙盒的文件交互
禁止行为：
- 将本地文件路径传递给沙盒工具操作
- 假设沙盒中可以直接读取本地生成的文件
- 在沙盒工具中引用本地环境的绝对路径
正确交互方式：
- 需要本地文件进入沙盒 → 先通过本地工具读取内容，再通过
createFile 写入沙盒
- 需要沙盒文件到本地 → 通过
readFile 读取内容，再通过本地工具写入本地路径
- 需要传递数据 → 使用变量或临时文件在沙盒内中转
工具方法详解
命令执行类
executeCommand
执行 shell 命令，每次调用在全新的 shell 进程中运行。
参数：
command: 要执行的 shell 命令（必填）workDir: 工作目录，默认 /workspacetimeout: 超时时间（秒），默认 120
重要提示：
- 环境变量和
cd 目录变更不会持久化到下一次调用
- 需要多步骤命令时，使用
&& 或 ; 连接，或写入脚本文件后执行
- 长时间运行的命令应使用
executeBackgroundCommand
executeBackgroundCommand
在后台执行长时间运行的命令。
参数：
command: 要执行的命令（必填）sessionName: 会话名称，用于后续跟踪（必填）workDir: 工作目录，默认 /workspace
管理后台任务：
- 查看输出：
checkBackgroundCommand(sessionName)
- 终止任务：
terminateBackgroundCommand(sessionName)
文件操作类
createFile
在沙盒中创建新文件。
参数：
filePath: 相对工作区的文件路径（如 dir/file.txt）content: 文件内容
readFile
读取沙盒中的文件内容。
参数：
strReplace
替换文件中唯一的文本内容（oldStr 必须在文件中恰好出现一次）。
参数：
filePath: 相对工作区的文件路径oldStr: 要替换的原始文本（必须唯一）newStr: 新文本
fullFileRewrite
完全重写已有文件的内容。
参数：
filePath: 相对工作区的文件路径content: 新内容
deleteFile
删除文件或目录。
参数：
listFiles
列出文件和目录。
参数：
dirPath: 相对工作区的目录路径，默认工作区根目录recursive: 是否递归列出，默认 false
moveFile / copyFile
移动/重命名或复制文件/目录。
参数：
sourcePath: 源路径destPath: 目标路径
getFileInfo
获取文件详细信息（大小、权限、修改时间等）。
参数：
makeDirectory
创建目录（自动创建父目录）。
参数：
tailFile
查看文件尾部内容（适合查看日志）。
参数：
filePath: 相对工作区的文件路径lines: 显示行数，默认 50
changePermissions
修改文件或目录权限。
参数：
filePath: 相对工作区的文件路径mode: 权限模式（如 755、644）recursive: 是否递归，默认 false
搜索与下载类
findInFiles
在文件中搜索文本（类似 grep）。
参数：
pattern: 搜索模式（必填）dirPath: 搜索目录，默认工作区根目录filePattern: 文件名过滤（如 *.java、*.py）
downloadResource
从 URL 下载资源到沙盒。
参数：
url: 资源 URL（必填）fileName: 保存的文件名（必填）
系统与扩展类
getSystemInfo
获取沙盒容器的系统信息（OS、内存、磁盘、进程等）。
installPackage
使用 apt-get 安装软件包（需要 root 权限）。
参数：
packages: 空格分隔的包名（如 python3 nodejs）
seeImage
读取图片文件并返回 Base64 编码（用于 AI 视觉识别）。
参数：
多工具协作规范
与本地文件工具的协作
场景：本地生成文件后需要在沙盒中处理
错误：直接传递本地路径给沙盒工具
createFile(filePath="D:\\local\\file.txt") // 沙盒中不存在此路径
正确：
1. 本地工具读取文件内容 → content
2. createFile(filePath="workspace/file.txt", content=content)
3. executeCommand(command="process workspace/file.txt")
场景：沙盒生成文件后需要在本地使用
错误：
假设沙盒文件可以直接在本地路径访问
正确：
1. readFile(filePath="output/result.txt") → content
2. 本地工具将 content 写入本地路径
与 Excel 工具的协作
场景：需要在沙盒中处理 Excel 文件
正确流程：
1. 本地生成/读取 Excel 文件内容
2. 如需在沙盒中处理，将文件内容或数据通过 createFile 传入沙盒（如转为 CSV）
3. 在沙盒中执行处理命令
4. 如需回到本地，通过 readFile 读取后由本地 Excel 工具处理
注意： 沙盒中生成的 Excel 文件无法直接通过本地 Excel 工具读取，必须先 readFile 或 downloadResource 将文件内容取出。
与代码编辑工具的协作
场景：需要编辑沙盒中的代码文件
优先使用沙盒工具：
- strReplace: 精确替换唯一文本
- fullFileRewrite: 完全重写文件
- createFile: 创建新文件
如需复杂编辑：
1. readFile 读取内容
2. 在上下文中规划修改
3. 使用 strReplace 或 fullFileRewrite 应用修改
常见错误与避免
| 错误类型 | 错误示例 | 正确做法 |
|---|
| 本地路径传入沙盒 | createFile(filePath="D:\\data\\file.txt") | createFile(filePath="data/file.txt") |
| 假设环境持久化 | 第一次调用 cd /tmp，第二次调用假设在 /tmp | 每次调用使用完整路径或 cd /tmp && command |
| 假设软件已安装 | 直接调用 python3 script.py 而不确认 | 先调用 getSystemInfo 或 executeCommand("which python3") 确认，必要时 installPackage |
| 混淆本地与沙盒文件 | 本地生成文件后直接让沙盒读取同一路径 | 通过 createFile 将内容显式传入沙盒 |
| 后台任务不跟踪 | 启动后台任务后不保存 sessionName | 记录 sessionName，使用 checkBackgroundCommand 跟踪 |
最佳实践
- 路径统一使用正斜杠：即使在 Windows 环境，沙盒内也是 Linux 路径，使用
/ 分隔
- 先检查再执行：执行命令前先用
listFiles 或 getFileInfo 确认文件存在
- 超时设置合理：根据命令预期执行时间设置
timeout，网络下载可设为 300 秒
- 后台任务必跟踪：使用
executeBackgroundCommand 时务必记录 sessionName
- 软件依赖先安装：在沙盒中运行代码前，先使用
installPackage 安装所需依赖
- 文件操作确认：写入重要文件后，使用
readFile 确认内容正确
- 环境信息先行：首次使用沙盒时，调用
getSystemInfo 了解环境配置
决策流程图
是否需要执行命令或操作文件？
├── 是 → 任务是否需要在隔离环境中运行？
│ ├── 是 → 使用 DockerSandboxTool
│ └── 否 → 仍建议使用 DockerSandboxTool（保证一致性）
└── 否 → 使用其他适当工具
使用 DockerSandboxTool 时：
1. 确认所有路径为沙盒内相对路径
2. 确认所需软件已安装（或先 installPackage）
3. 执行操作
4. 验证结果（readFile / listFiles / executeCommand）
