docker-tool-specification

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（这些是本地路径，沙盒中不存在）

本地与沙盒的文件交互

禁止行为：

• 将本地文件路径传递给沙盒工具操作
• 假设沙盒中可以直接读取本地生成的文件
• 在沙盒工具中引用本地环境的绝对路径

正确交互方式：

1. 需要本地文件进入沙盒 → 先通过本地工具读取内容，再通过 createFile 写入沙盒
2. 需要沙盒文件到本地 → 通过 readFile 读取内容，再通过本地工具写入本地路径
3. 需要传递数据 → 使用变量或临时文件在沙盒内中转

工具方法详解

命令执行类

executeCommand

执行 shell 命令，每次调用在全新的 shell 进程中运行。

参数：

• command: 要执行的 shell 命令（必填）
• workDir: 工作目录，默认 /workspace
• timeout: 超时时间（秒），默认 120

重要提示：

• 环境变量和 cd 目录变更不会持久化到下一次调用
• 需要多步骤命令时，使用 && 或 ; 连接，或写入脚本文件后执行
• 长时间运行的命令应使用 executeBackgroundCommand

executeBackgroundCommand

在后台执行长时间运行的命令。

参数：

• command: 要执行的命令（必填）
• sessionName: 会话名称，用于后续跟踪（必填）
• workDir: 工作目录，默认 /workspace

管理后台任务：

• 查看输出：checkBackgroundCommand(sessionName)
• 终止任务：terminateBackgroundCommand(sessionName)

文件操作类

createFile

在沙盒中创建新文件。

参数：

• filePath: 相对工作区的文件路径（如 dir/file.txt）
• content: 文件内容

readFile

读取沙盒中的文件内容。

参数：

• filePath: 相对工作区的文件路径

strReplace

替换文件中唯一的文本内容（oldStr 必须在文件中恰好出现一次）。

参数：

• filePath: 相对工作区的文件路径
• oldStr: 要替换的原始文本（必须唯一）
• newStr: 新文本

fullFileRewrite

完全重写已有文件的内容。

参数：

• filePath: 相对工作区的文件路径
• content: 新内容

deleteFile

删除文件或目录。

参数：

• filePath: 相对工作区的文件路径

listFiles

列出文件和目录。

参数：

• dirPath: 相对工作区的目录路径，默认工作区根目录
• recursive: 是否递归列出，默认 false

moveFile / copyFile

移动/重命名或复制文件/目录。

参数：

• sourcePath: 源路径
• destPath: 目标路径

getFileInfo

获取文件详细信息（大小、权限、修改时间等）。

参数：

• filePath: 相对工作区的文件路径

makeDirectory

创建目录（自动创建父目录）。

参数：

• dirPath: 相对工作区的目录路径

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 视觉识别）。

参数：

• filePath: 相对工作区的图片路径

多工具协作规范

与本地文件工具的协作

场景：本地生成文件后需要在沙盒中处理

错误：直接传递本地路径给沙盒工具
  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 跟踪

最佳实践

1. 路径统一使用正斜杠：即使在 Windows 环境，沙盒内也是 Linux 路径，使用 / 分隔
2. 先检查再执行：执行命令前先用 listFiles 或 getFileInfo 确认文件存在
3. 超时设置合理：根据命令预期执行时间设置 timeout，网络下载可设为 300 秒
4. 后台任务必跟踪：使用 executeBackgroundCommand 时务必记录 sessionName
5. 软件依赖先安装：在沙盒中运行代码前，先使用 installPackage 安装所需依赖
6. 文件操作确认：写入重要文件后，使用 readFile 确认内容正确
7. 环境信息先行：首次使用沙盒时，调用 getSystemInfo 了解环境配置

决策流程图

是否需要执行命令或操作文件？
  ├── 是 → 任务是否需要在隔离环境中运行？
  │         ├── 是 → 使用 DockerSandboxTool
  │         └── 否 → 仍建议使用 DockerSandboxTool（保证一致性）
  └── 否 → 使用其他适当工具

使用 DockerSandboxTool 时：
  1. 确认所有路径为沙盒内相对路径
  2. 确认所需软件已安装（或先 installPackage）
  3. 执行操作
  4. 验证结果（readFile / listFiles / executeCommand）