feat: add CUA computer-use sandbox support (#7828)

* feat: add CUA computer-use sandbox support

* fix: add CUA config metadata translations

* fix: address CUA sandbox review feedback

* fix: default CUA sandbox to local mode

* fix: harden CUA SDK method compatibility

* fix: harden CUA GUI and permission handling

* fix: refine CUA capability and shell handling

* fix: avoid inline CUA screenshot image results by default

* fix: guide CUA browser startup workflow

* feat: add CUA browser and key press tools

* fix: launch CUA browser as sandbox user

* fix: stabilize CUA browser screenshots

* fix: simplify CUA browser launch command

* fix: remove CUA open browser tool

* fix: align CUA desktop control guidance

* fix: harden CUA shell background handling

* fix: harden CUA runtime adapters

* fix: surface CUA filesystem failures

* fix: clarify CUA shell fallback support

* fix: harden CUA shell helpers

* fix: guard CUA file fallbacks

* fix: redact sensitive config log paths

* fix: guard CUA download fallback

* test: cover CUA GUI and shell env wiring

* fix: preserve CUA command result output

* fix: normalize CUA return codes

* fix: preserve foreground shell behavior

* fix: clean up failed CUA boots

* docs: add CUA sandbox runtime guide

* test: cover CUA GUI tool registration

* refactor: simplify CUA fallback handling

* refactor: simplify CUA shell helpers

* test: cover CUA screenshot result shapes

docs/zh/use/astrbot-agent-sandbox.md

@@ -13,11 +13,12 @@
 
 - `Shipyard Neo`（当前推荐）
 - `Shipyard`（旧方案，仍可继续使用）
+- `CUA`（本地或云端电脑使用沙盒，适合需要桌面操作的场景）
 
 在当前版本的 AstrBot 控制台中，可在“AI 配置” -> “Agent Computer Use”中选择：
 
 - `Computer Use Runtime` = `sandbox`
-- `沙箱环境驱动器` = `Shipyard Neo` 或 `Shipyard`
+- `沙箱环境驱动器` = `Shipyard Neo`、`Shipyard` 或 `CUA`
 
 其中，`Shipyard Neo` 是当前默认驱动器。它由 Bay、Ship、Gull 三部分组成：
 
@@ -30,6 +31,109 @@
 > [!TIP]
 > `Shipyard Neo` 下浏览器能力并不是所有 profile 都有。只有 profile 支持 `browser` capability 时，AstrBot 才会挂载浏览器相关工具。典型 profile 如 `browser-python`。
 
+## CUA 运行时
+
+`CUA` 是一个面向电脑使用（Computer Use）的沙盒运行时。它可以通过统一的 Python SDK 创建 Linux、macOS、Windows、Android 等不同类型的沙盒，并暴露 Shell、截图、鼠标、键盘、文件系统等接口。
+
+在 AstrBot 中选择 `CUA` 驱动器后，Agent 可以在 CUA sandbox 中使用：
+
+- Shell 工具
+- Python 工具
+- 文件读取、写入、编辑和搜索工具
+- 截图工具
+- 鼠标点击工具
+- 键盘输入工具
+- 沙盒文件上传与下载工具
+
+> [!NOTE]
+> CUA 是可选运行时，AstrBot 默认安装不会强制安装它。如果选择了 `CUA` 但当前 Python 环境没有安装 `cua` 包，启动沙盒时会提示安装缺失。
+
+### 安装 CUA 依赖
+
+如果您通过源码或虚拟环境运行 AstrBot，请在 AstrBot 使用的 Python 环境中安装 CUA：
+
+```bash
+pip install cua
+```
+
+如果您使用 `uv` 管理 AstrBot 环境，可在 AstrBot 项目目录中执行：
+
+```bash
+uv pip install cua
+```
+
+CUA 本身还依赖具体运行方式：
+
+- 本地 Linux 容器通常需要 Docker 可用。
+- 本地 Linux/Windows VM 通常需要 QEMU 或 CUA 对应的本地运行时。
+- macOS VM 通常依赖 CUA/Lume 相关运行时。
+- 云端 CUA 需要可用的 CUA API Key。
+
+具体宿主机要求、镜像支持情况和本地运行时安装方式，请参考 [CUA 官方文档](https://cua.ai/docs)。
+
+### 在 AstrBot 中配置 CUA
+
+进入 WebUI：
+
+- `配置 -> 普通配置 -> 使用电脑能力`
+
+然后设置：
+
+- `Computer Use Runtime` = `sandbox`
+- `沙箱环境驱动器` = `CUA`
+
+CUA 相关配置项包括：
+
+- `CUA Image`：要启动的 CUA 镜像。常见值为 `linux`、`macos`、`windows`、`android`。默认 `linux`。
+- `CUA OS Type`：镜像的操作系统类型。默认 `linux`。它会影响 AstrBot 对 POSIX Shell fallback 的判断。
+- `CUA Sandbox TTL`：沙盒生命周期，单位为秒。默认 `3600`。
+- `CUA Telemetry Enabled`：是否启用 CUA 侧遥测。默认关闭。
+- `CUA Local Runtime`：是否使用本地运行时。默认开启。关闭后会按 CUA SDK 的云端方式创建沙盒。
+- `CUA API Key`：云端 CUA 所需的 API Key。仅在使用云端运行时时填写。
+
+一个最小本地 Linux 容器配置通常是：
+
+```text
+Computer Use Runtime = sandbox
+沙箱环境驱动器 = CUA
+CUA Image = linux
+CUA OS Type = linux
+CUA Local Runtime = true
+CUA Sandbox TTL = 3600
+```
+
+如果使用云端 CUA，可改为：
+
+```text
+Computer Use Runtime = sandbox
+沙箱环境驱动器 = CUA
+CUA Image = linux
+CUA OS Type = linux
+CUA Local Runtime = false
+CUA API Key = <your-cua-api-key>
+```
+
+> [!WARNING]
+> 不要把 CUA API Key 写入公开日志、截图或 issue。AstrBot 的运行日志不会输出该字段，但部署平台、Shell 历史和容器环境变量仍需自行保护。
+
+### 使用 CUA 时的注意事项
+
+- `linux` 镜像通常适合 Shell、Python、文件系统和桌面自动化测试。
+- 非 POSIX 镜像（如 `windows`、`android`）不一定支持 `sh`、`cat`、`ls`、`rm`、`base64` 等命令。AstrBot 对需要这些命令的 fallback 操作会返回明确错误。
+- 如果需要在 CUA sandbox 中打开浏览器或 GUI 程序，通常应使用 Shell 后台执行，例如显式传入 `background=true`，避免命令阻塞后续工具调用。
+- 直接把 sandbox 内的文件路径发送给用户通常不可行。应优先使用 AstrBot 的沙盒下载工具，将文件下载到 AstrBot 临时目录后再发送。
+- CUA 与 Shipyard Neo 的 workspace 语义不同。Shipyard Neo 固定使用 `/workspace`；CUA 的工作目录和文件路径取决于镜像与运行时。
+
+### 何时选择 CUA
+
+建议在以下场景选择 `CUA`：
+
+- 需要桌面截图、鼠标点击、键盘输入等 GUI 自动化能力。
+- 需要测试不同 OS 镜像中的行为，例如 Linux、Windows、Android。
+- 已经在本机或云端部署好 CUA 运行环境。
+
+如果只是需要稳定的 Python/Shell/文件系统沙盒，且不需要桌面 GUI 操作，通常优先选择 `Shipyard Neo`。它与 AstrBot 的 workspace、Skills 同步和长期运行模式更贴合。
+
 ## 性能要求
 
 AstrBot 给每个沙盒环境限制最高 1 CPU 和 512 MB 内存。
@@ -388,4 +492,4 @@ Shipyard 会自动将沙盒环境中的 /home 目录挂载到宿主机的 `${PWD
 
 ### luosheng520qaq/astrobot_plugin_code_executor
 
-如果您资源有限，不希望使用沙盒环境来执行代码，可以尝试 luosheng520qaq 开发的 [astrobot_plugin_code_executor](https://github.com/luosheng520qaq/astrobot_plugin_code_executor) 插件。该插件会直接在宿主机上执行代码。插件已经尽力提升安全性，但仍需留意代码安全性问题。
+如果您资源有限，不希望使用沙盒环境来执行代码，可以尝试 luosheng520qaq 开发的 [astrobot_plugin_code_executor](https://github.com/luosheng520qaq/astrobot_plugin_code_executor) 插件。该插件会直接在宿主机上执行代码。插件已经尽力提升安全性，但仍需留意代码安全性问题。

docs/zh/use/computer.md

@@ -97,7 +97,12 @@ data/workspaces/{normalized_umo}/notes/todo.txt
 
 在沙盒中，Agent 仍然可以使用 Shell、Python、文件系统工具；如果所选沙盒 profile 支持 `browser` capability，还会挂载浏览器自动化工具。
 
-使用 Shipyard Neo 时，沙盒 workspace 根目录通常是：
+沙盒环境驱动器可在 `配置 -> 普通配置 -> 使用电脑能力` 的沙箱配置中选择。当前常用选项包括：
+
+- `Shipyard Neo`：AstrBot 推荐的远程/独立部署沙盒服务，适合长期运行和多人使用。
+- `CUA`：基于 [CUA](https://github.com/trycua/cua) 的本地或云端电脑使用沙盒，可提供桌面截图、鼠标、键盘、Shell、Python 和文件系统能力。
+
+使用 `Shipyard Neo` 时，沙盒 workspace 根目录通常是：
 
 ```text
 /workspace
@@ -115,7 +120,9 @@ result.txt
 /workspace/result.txt
 ```
 
-沙盒部署、profile、TTL、数据持久化、浏览器能力等内容请参考：[Agent 沙盒环境](/use/astrbot-agent-sandbox)。
+使用 `CUA` 时，工作目录和可用命令取决于所选 CUA image 与运行方式。Linux CUA 容器通常提供类 Unix Shell；Windows、Android 等非 POSIX 镜像不保证支持 `sh`、`ls`、`rm`、`base64` 等命令，AstrBot 会对部分 shell fallback 操作返回明确错误。
+
+沙盒部署、驱动器选择、CUA 配置、profile、TTL、数据持久化、浏览器能力等内容请参考：[Agent 沙盒环境](/use/astrbot-agent-sandbox)。
 
 > [!NOTE]
 > 即使在 `sandbox` 模式下，“需要 AstrBot 管理员权限”仍会影响 Shell、Python、浏览器、上传下载等工具的调用权限。具体权限取决于你的配置。