NekoWorker

给 AI Agent 使用的完整 Linux 桌面，支持 Docker 和无 Docker 的本机部署。通过 MCP 操作桌面应用、系统窗口、文件管理器、终端和浏览器；通过 AT-SPI 元素树提供纯文本模型可读的界面信息，通过 noVNC 供人实时观察和接管。

当前为单桌面 MVP。每个 Compose 项目启动一套独立桌面；不内置 LLM，也不绑定某个模型供应商。

不使用 Docker（Ubuntu / Debian）

./scripts/install-native.sh   # 首次安装依赖，需要 sudo；Python 环境属于普通用户
./scripts/native.sh up        # 普通用户启动，不使用 sudo
./scripts/native.sh status
./scripts/native.sh down      # 停止，保留文件

此模式创建独立 Xvfb 显示、D-Bus 会话、XFCE 桌面和应用配置目录。MCP 工具与 Docker 模式相同。默认地址为桌面 http://127.0.0.1:6081/vnc.html 和 MCP http://127.0.0.1:8081/mcp，可与 Docker 模式同时运行。凭证保存于 .native/credentials.json，文件/日志/桌面配置保存在权限为 700 的 .native/。工作目录为 .native/workspace。启动自动等待全部服务运行并通过健康检查。

./scripts/native.sh up --mcp-port 8082 --desktop-port 6082 --vnc-port 5902
./scripts/native.sh stdio     # Agent stdio 接入，复用该桌面的 X11 和 D-Bus
# 独立实例；--state-dir 放在 up / down / status / stdio 子命令之前
./scripts/native.sh --state-dir /tmp/neko-second up --mcp-port 8083 --desktop-port 6083 --vnc-port 5903

这是桌面会话隔离，没有文件系统、进程或网络隔离。应用以启动用户的权限运行，可以访问该用户的宿主机文件；单独设置 HOME 并不构成沙箱。需要安全边界但不想使用 Docker 时，可在独立用户或虚拟机内部署。

此安装脚本不改写宿主浏览器的系统策略，也不自动安装 Ubuntu 的 Snap Firefox。可自行安装浏览器；Firefox 要开启无障碍支持时，在该实例使用的浏览器配置中设置 accessibility.force_disabled=-1；Chromium/Electron 可使用 --force-renderer-accessibility。原生 GTK 应用无需这些浏览器配置。日志见 .native/launcher.log 与 .native/*-stderr-*.log。主机重启后需重新执行 up。

Related MCP server: mcp-linux-desktop

Docker 一键部署

需要 Linux Docker Engine、Docker Compose v2、Python 3。首次构建需要联网下载 Debian、桌面及 Python 依赖，建议至少 2 核 / 4 GB 内存。

./scripts/up.sh
# 或 make up

首次自动创建权限为 600 的 .env，写入随机 MCP Token 和 VNC 密码。启动脚本等待容器健康检查通过后返回。

• 桌面：http://127.0.0.1:6080/vnc.html，输入 .env 中 NEKO_VNC_PASSWORD。

• MCP：http://127.0.0.1:8080/mcp，Streamable HTTP，使用 Authorization: Bearer <NEKO_TOKEN>。

• 健康检查：http://127.0.0.1:8080/healthz，检查 MCP 进程与 X11 连通性，不要求 Token；不代表每个应用的 AT-SPI 都正常。

docker compose logs -f
docker compose down           # 停止，保留桌面文件和工作区
docker compose up -d --wait    # 再次启动
# docker compose down -v 会删除持久数据，不用于日常停止

可参考 .env.example 调整分辨率、资源、端口、绑定地址和构建镜像源。启动后修改 .env，再运行 docker compose up -d。默认仅绑定宿主机回环地址。远程使用建议 SSH 转发两个端口；如自行开放监听，需自行配置 TLS 和网络访问控制。VNC 是传统八字符密码认证，无内置 TLS；MCP Token 可执行桌面用户权限内的任意程序，不应给不可信 Agent。容器没有宿主 Docker socket、特权模式或宿主目录挂载。

桌面用户为 UID 1000 的 agent，无 sudo。/home/agent 和 /workspace 是命名持久卷。应用可通过 desktop_launch 启动；安装额外系统包请修改 Dockerfile 后重建。

Agent 接入

支持远程 MCP 的客户端通常可使用以下配置，字段名以客户端为准：

{
  "mcpServers": {
    "nekoworker": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {"Authorization": "Bearer <从 .env 读取 NEKO_TOKEN>"}
    }
  }
}

也可在已运行的桌面容器内用 stdio（复用 MCP 服务进程的 D-Bus 地址）：

docker compose exec -T desktop sh -c 'export DBUS_SESSION_BUS_ADDRESS="$(cat /tmp/runtime-agent/session-bus)"; exec nekoworker --transport stdio'

示例 MCP SDK 客户端见 examples/client.py。

桌面能力

推荐循环：desktop_tree → desktop_element → desktop_tree。树返回的 actions 是应用真实声明的动作名称，不保证都叫 click。需要输入时优先 set_text（原生填入无效时自动聚焦、全选并粘贴，会改写剪贴板）；不可编辑元素可聚焦后 desktop_type_text。粘贴工具会改写剪贴板，终端通常用 desktop_type_text(text="命令", paste_keys="ctrl+shift+v")。应用状态变化异步发生，每次操作后需重新观察。

元素 ID 属于最近一次树快照，下次读取树会使旧 ID 失效。执行时还检查路径、角色、名称和应用 PID；这是尽力校验，界面在校验与动作之间仍可能变化，同名同角色的替换元素也无法完全识别。不要把 ID 当永久选择器。一个桌面只让一个 Agent 控制；并发客户端会共享焦点、剪贴板和快照。

元素树覆盖范围

使用系统 AT-SPI，无需注入浏览器 DOM。GTK 应用通常有较好的树；Firefox、Qt、Electron 的效果取决于应用的无障碍实现。镜像已设置 GTK/Qt 无障碍环境变量，并通过 Firefox 企业策略强制启用无障碍接口；Chromium/Electron 应用建议显式传入 --force-renderer-accessibility。自绘 Canvas、游戏、部分远程桌面应用可能没有可用元素，此时仍需要键鼠和截图；本项目不把这些界面虚构为可读元素。

树省略角色为 password text 的文本，但应用可能在其他元素中暴露敏感内容，截图也可能包含密码、个人数据。树按预算截断并明确返回 truncated；Firefox 等层级较深的应用可用 max_depth=30 并按应用筛选。每次操作在单独子进程中执行，默认 20 秒超时，避免一个应用的 D-Bus 卡住整个 MCP 服务。

实现结构

Agent ── MCP HTTP + Bearer / stdio ── MCP 服务
                                       │ 限时工作进程
                                       ├─ AT-SPI → 原生应用元素树 / 语义动作
                                       ├─ X11 → 窗口 / 键鼠 / 截图
                                       └─ 应用进程 → 桌面用户权限
人 ── noVNC + VNC 密码 ── x11vnc ── 同一个 XFCE/Xvfb 桌面

所有服务使用同一用户、DISPLAY 和 D-Bus 会话。Supervisor 管理并重启进程，tini 回收孤儿。MCP 使用官方 Python SDK 的维护版本线 mcp>=1.28,<2；当前交付不包含多租户容器调度、录屏、OCR 或独立管理控制台。

参考了本地 Octop 的 docker/Dockerfile、docker/docker-compose.yml 和 src/octop/infra/backend/docker_spec.py 中的 Docker/Compose、持久化、健康检查和资源参数模式，桌面控制实现独立编写。来源及许可证见 docs/attribution.md。

本地开发与验证

Linux 需安装 Xvfb、AT-SPI、GTK、D-Bus、xdotool、xclip、wmctrl。Python 虚拟环境必须能读取系统包（pyatspi / GI 不从 pip 安装）：

python3 -m venv --system-site-packages .venv
.venv/bin/pip install -e '.[dev]'
make check
./scripts/test-desktop.sh

集成测试在独立 Xvfb 和 D-Bus 会话启动 GTK 测试程序，用真实 MCP HTTP 客户端验证鉴权、工具发现、元素树、中文填写、按钮动作、截图、过期 ID 和键鼠粘贴。不会操作当前登录桌面。

容器集成验证：./scripts/test-container.sh，额外验证 noVNC WebSocket/RFB 密码握手与 Firefox 网页输入框的元素树和中文填写。Python 运行依赖已锁定在 requirements.lock，镜像构建从该文件安装。