feat(dev): add Linux dev container

.devcontainer/Dockerfile

@@ -0,0 +1,21 @@
+ARG PYTHON_VERSION=3.13
+FROM mcr.microsoft.com/devcontainers/python:1-${PYTHON_VERSION}-bookworm
+
+# Keep the development image aligned with the runtime image for media tooling.
+RUN rm -f /etc/apt/sources.list.d/yarn.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+ENV UV_PROJECT_ENVIRONMENT=/opt/venv \
+    PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright \
+    HF_HOME=/home/vscode/.cache/huggingface
+
+# Cache the large Python and browser dependencies independently from source edits.
+WORKDIR /tmp/coworker-dependencies
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-install-project \
+    && /opt/venv/bin/playwright install --with-deps chromium \
+    && chown -R vscode:vscode /opt/venv /opt/ms-playwright

.devcontainer/devcontainer-lock.json

@@ -0,0 +1,9 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "1.7.1",
+      "resolved": "ghcr.io/devcontainers/features/node@sha256:8c0de46939b61958041700ee89e3493f3b2e4131a06dc46b4d9423427d06e5f6",
+      "integrity": "sha256:8c0de46939b61958041700ee89e3493f3b2e4131a06dc46b4d9423427d06e5f6"
+    }
+  }
+}

.devcontainer/devcontainer.json

@@ -0,0 +1,45 @@
+{
+  "name": "CoWorker",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "..",
+    "args": {
+      "PYTHON_VERSION": "3.13"
+    }
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "24"
+    }
+  },
+  "remoteUser": "vscode",
+  "updateRemoteUserUID": true,
+  "containerEnv": {
+    "API__HOST": "0.0.0.0"
+  },
+  "postCreateCommand": "uv sync --frozen --dev",
+  "forwardPorts": [
+    8000,
+    8100
+  ],
+  "portsAttributes": {
+    "8000": {
+      "label": "CoWorker API"
+    },
+    "8100": {
+      "label": "Explore Lab"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.defaultInterpreterPath": "/opt/venv/bin/python",
+        "python.terminal.activateEnvironment": true
+      },
+      "extensions": [
+        "ms-python.python",
+        "charliermarsh.ruff"
+      ]
+    }
+  }
+}

README.en.md

@@ -164,6 +164,11 @@ The current `pyproject.toml` uses the PyTorch CPU index on every platform. To us
 on Windows or Linux, switch the `torch` source as shown in that file, then run
 `uv lock && uv sync`.
 
+> [!NOTE]
+> Intel macOS cannot install the current PyTorch wheel. Use the checked-in
+> [Dev Container](docs/development/development.en.md#dev-container) to develop and test Python
+> code in a Linux x86_64 container.
+
 Coworker starts the agent loop, file inbox watcher, and FastAPI service together. The API is available at `http://localhost:8000` by default.
 
 > [!TIP]

README.md

@@ -163,6 +163,11 @@ uv run python -m coworker
 上使用 NVIDIA GPU（CUDA 13.0），请按文件中的注释切换 `torch` source，再执行
 `uv lock && uv sync`。
 
+> [!NOTE]
+> Intel macOS 无法安装当前版本的 PyTorch wheel。请使用仓库内的
+> [Dev Container](docs/development/development.md#dev-container)，在 Linux x86_64
+> 容器中完成 Python 开发和测试。
+
 启动后，Agent 循环、文件 inbox 监听和 FastAPI 服务会同时运行。默认 API 地址为 `http://localhost:8000`。
 
 > [!TIP]

docs/development/development.en.md

@@ -33,6 +33,30 @@ git status --short -- src/coworker/web
 
 On Debian or Ubuntu, use `uv run playwright install --with-deps chromium` if the required browser system libraries are missing.
 
+### Dev Container
+
+The current PyTorch release no longer provides a `macosx_x86_64` wheel for Intel macOS. The
+checked-in [`.devcontainer`](../../.devcontainer/devcontainer.json) configuration runs the
+development environment in Linux, so an Intel Mac uses PyTorch's `linux/x86_64` CPU wheel.
+Apple Silicon uses native `linux/arm64` without forced x86 emulation.
+
+Install Docker Desktop (or a compatible container runtime) and the VS Code Dev Containers
+extension, then run **Dev Containers: Reopen in Container** from the repository. The first build:
+
+- installs Python 3.13, uv, Node.js 24, and FFmpeg;
+- installs the locked Python development dependencies and Linux CPU build of PyTorch;
+- installs Playwright Chromium and its Linux system libraries;
+- forwards port `8000` for the CoWorker API and `8100` for Explore Lab.
+
+The source checkout remains bind-mounted from the host, while the container's Python environment
+lives at `/opt/venv`. After creation, run the `uv run ...`, `npm ...`, and test commands from this
+guide directly. Run **Dev Containers: Rebuild Container** after dependency or lockfile changes to
+refresh the cached layers.
+
+The Dev Container is a Linux environment. It supports Python, web, and Explore Lab development,
+but cannot build or validate macOS-specific Tauri `.app`/`.dmg` artifacts, signing, or
+notarization. Continue to perform those tasks on macOS or a matching CI runner.
+
 ### Explore Lab
 
 The Explore Lab backend can serve the frontend build directly. Branch runtimes use virtual communication participants (`explore_lab` by default): `communicate` records outbound messages in branch state without external delivery, and `list_connections` reports those virtual participants as active connections. Normal use requires starting only the backend after building the UI:

docs/development/development.md

@@ -36,6 +36,29 @@ git status --short -- src/coworker/web
 Debian/Ubuntu 如果缺少浏览器系统库，使用
 `uv run playwright install --with-deps chromium`。
 
+### Dev Container
+
+在 Intel macOS 上，当前 PyTorch 版本不再提供 `macosx_x86_64` wheel。仓库内的
+[`.devcontainer`](../../.devcontainer/devcontainer.json) 配置会把开发环境运行在
+Linux 容器中，因此 Intel Mac 会使用 PyTorch 的 `linux/x86_64` CPU wheel；Apple
+Silicon 则使用原生 `linux/arm64`，不需要强制模拟 x86。
+
+先安装 Docker Desktop（或兼容的容器运行时）以及 VS Code 的 Dev Containers
+扩展，然后在仓库目录执行 **Dev Containers: Reopen in Container**。首次构建会：
+
+- 安装 Python 3.13、uv、Node.js 24 和 FFmpeg；
+- 通过锁文件安装 Python 开发依赖和 Linux CPU 版 PyTorch；
+- 安装 Playwright Chromium 及其 Linux 系统库；
+- 转发 CoWorker API 的 `8000` 端口和 Explore Lab 的 `8100` 端口。
+
+源码仍由宿主机目录挂载，容器内的 Python 环境位于 `/opt/venv`。容器创建完成后，
+可直接运行本文中的 `uv run ...`、`npm ...` 和测试命令。依赖或锁文件发生变化后，
+执行 **Dev Containers: Rebuild Container** 以刷新缓存层。
+
+Dev Container 是 Linux 环境，适合 Python、Web 和 Explore Lab 开发，但不能生成或
+验证 macOS 专属的 Tauri `.app`/`.dmg`、签名和公证；这些步骤仍需在 macOS 本机或
+对应的 CI runner 上完成。
+
 ### Explore Lab
 
 Explore Lab 的后端可以直接托管前端构建产物，日常使用只需要启动后端。分支运行时使用模拟通信对象（默认 `explore_lab`）：`communicate` 只把出站消息记录到分支状态，不会投递到外部；`list_connections` 会将这些模拟对象显示为活跃连接。