1.1. 工具层 (Tool Layer)#

• 位置: astrbot.core.tools.computer_tools.*
• 职责: 这些是直接暴露给大语言模型 (LLM) 使用的 Function Call 工具（例如 PythonTool、ExecuteShellTool、FileReadTool 等）。工具层负责接收 LLM 传入的参数，进行系统级别的权限校验（如判断是否为管理员），然后根据当前上下文获取对应的沙盒实例。拿到实例后，工具会将具体任务委托给沙盒内部的各个组件去执行，并将结果格式化返回给大模型。

1.2. 路由与生命周期层 (Client Routing Layer)#

• 位置: astrbot.core.computer.computer_client.py 中的 get_booter 函数。
• 职责: 充当沙盒的工厂与连接池。当工具层请求一个沙盒环境时，get_booter 会根据用户配置（provider_settings.sandbox.booter）决定实例化哪种具体的沙盒（如 shipyard_neo, shipyard, boxlite 等）。为了实现会话维度的隔离和状态保持，它维护了一个以 Session ID（统一消息来源 umo）为键的连接池。如果当前 Session 尚未启动沙盒，它负责调用对应 Booter 的 boot() 方法进行初始化。

1.3. 抽象组件层 (olayer)#

• 位置: astrbot.core.computer.olayer.*
• 职责: 为工具层提供统一的接口协议（Protocol），抹平不同底层沙盒的 API 差异。定义了以下标准组件能力：
  • ShellComponent: 执行终端命令
  • PythonComponent: 执行 Python 代码
  • FileSystemComponent: 提供文件操作（读取、写入、编辑、搜索等）
  • BrowserComponent: 执行浏览器自动化操作

1.4. 沙盒实现层 (Booters Layer)#

• 位置: astrbot.core.computer.booters.*
• 职责: 针对具体的底层沙盒架构（如 ShipyardNeoBooter、BoxliteBooter），实现上述的 olayer 组件协议。这些具体组件在内部通过其专属的 SDK 或网络请求，与远程或本地隔离的沙盒服务进行真正的指令通讯。

3.1. 文件上传实现 (FileUploadTool)#

当用户通过聊天界面发送了一份文件，大模型需要在沙盒内处理该文件时，会触发此工具。

1. 入参: local_path (宿主机上该文件的绝对路径)。
2. 处理逻辑:
   • 获取到当前的沙盒 Booter。
   • 解析出文件名：remote_path = os.path.basename(local_path)。默认将文件存放到沙盒内部的当前工作目录下。
   • 调用 sb.upload_file(local_path, remote_path) 交由底层沙盒层处理。
3. 底层协议实现 (以 ShipyardNeoBooter 为例):
   • Booter 会在宿主机读取 local_path 的二进制字节流 (content = f.read())。
   • 调用远程沙盒 SDK _sandbox.filesystem.upload(remote_path, content) 将字节流发送入沙盒。
   • 若是 BoxliteBooter，底层则会构造 aiohttp.FormData 进行 multipart/form-data 的 HTTP POST 请求上传至本地的 Boxlite 容器中。

3.2. 文件下载实现 (FileDownloadTool)#

当沙盒中的代码生成了产物（如数据图表、处理后的 Excel 等），大模型希望将这份文件导出给用户时，会触发此工具。

1. 入参: remote_path (文件在沙盒内部的路径)，also_send_to_user (是否自动发送给用户，默认 true)。
2. 处理逻辑:
   • 获取到当前的沙盒 Booter。
   • 在宿主机的 get_astrbot_temp_path() (系统临时目录) 下生成一个带 UUID 的防冲突本地路径，如 sandbox_a1b2_output.png。
   • 调用 sb.download_file(remote_path, local_path) 将文件从沙盒拉出并落盘到宿主机的临时目录下。
3. 底层协议实现 (以 ShipyardNeoBooter 为例):
   • 调用 SDK _sandbox.filesystem.download(remote_path) 请求文件流。
   • 将收到的二进制内容以 "wb" 模式写入到宿主机的 local_path 中。
4. 回传用户:
   • 若 also_send_to_user 为 True，工具内部会构建一个 AstrBot 专用的消息链 (MessageChain)，把下载到本地的物理文件包装为 File(name=..., file=local_path) 发送至聊天平台，此时用户即可在聊天框收到文件。

3.3. 路径安全与边界隔离差异#

• 在 Local 模式下的文件读写工具（fs.py 中的 FileReadTool / FileWriteTool 等），出于安全考虑，会在工具层通过 _normalize_rw_path 进行严格的软拦截和约束，防止越权读取。
• 在 Sandbox 模式下，所有的文件读写、编辑、搜索等路径传参几乎直接进行透传。原因是：工具层将所有的操作路径边界安全交给了真正的底层沙盒环境来保证，达到了真正的沙盒级物理隔离，这使得设计异常干净清晰。