diff --git a/docs/case/combination_tests.md b/docs/case/combination_tests.md
new file mode 100644
index 0000000..ab9964a
--- /dev/null
+++ b/docs/case/combination_tests.md
@@ -0,0 +1,102 @@
+# 组合测试用例
+
+本文档定义了 `setup-ai-workspace-all-in-one.sh` 的端到端组合测试矩阵。
+
+## 测试前置条件
+
+| 条件 | 说明 |
+|------|------|
+| 支持平台 | macOS (Darwin) / Debian / Ubuntu |
+| 必备工具 | `curl`、`bash`（macOS 额外需要 `brew`） |
+| 网络要求 | 可访问 GitHub / npm registry |
+
+---
+
+## 测试矩阵
+
+### COMBO-001: 全新安装（无 API Key）
+
+```bash
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -
+```
+
+**预期结果**: 安装完成，LiteLLM 等服务以空配置启动，控制台可访问。
+
+---
+
+### COMBO-002: 全新安装 + API Key 注入
+
+```bash
+export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+export NVIDIA_API_KEY="nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+export OLLAMA_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx"
+
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -
+```
+
+**预期结果**: 安装完成，API Key 自动注入 LiteLLM 配置，AI 模型网关可正常代理请求。
+
+---
+
+### COMBO-003: 卸载（保留数据）
+
+```bash
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -s -- uninstall
+```
+
+**预期结果**: 停止所有服务，移除运行时文件，保留用户数据和配置。
+
+---
+
+### COMBO-004: 彻底卸载（清除所有数据）
+
+```bash
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -s -- uninstall --purge
+```
+
+**预期结果**: 停止所有服务，移除运行时文件，清除所有用户数据、配置和本地数据库。
+
+---
+
+### COMBO-005: 卸载后重装（完整生命周期）
+
+```bash
+# Step 1: 彻底卸载
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -s -- uninstall --purge
+
+# Step 2: 带 Key 重装
+export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+export NVIDIA_API_KEY="nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+export OLLAMA_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx"
+
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -
+```
+
+**预期结果**: 卸载干净无残留，重装后一切正常运行，API Key 正确注入。
+
+---
+
+### COMBO-006: 幂等性测试（重复安装）
+
+```bash
+# 连续执行两次安装
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -
+```
+
+**预期结果**: 第二次运行应以幂等方式完成，不产生错误，`changed` 计数应接近 0。
+
+---
+
+## 平台覆盖矩阵
+
+| 测试编号 | macOS (Darwin) | Debian | Ubuntu |
+|----------|:--------------:|:------:|:------:|
+| COMBO-001 | ✅ | ✅ | ✅ |
+| COMBO-002 | ✅ | ✅ | ✅ |
+| COMBO-003 | ✅ | ✅ | ✅ |
+| COMBO-004 | ✅ | ✅ | ✅ |
+| COMBO-005 | ✅ | ✅ | ✅ |
+| COMBO-006 | ✅ | ✅ | ✅ |
+
+> **注意**: 目前仅 macOS / Debian / Ubuntu 经过实际测试验证，其他 Linux 发行版未测试。
diff --git a/docs/case/macos_compatibility_tests.md b/docs/case/macos_compatibility_tests.md
new file mode 100644
index 0000000..f62f409
--- /dev/null
+++ b/docs/case/macos_compatibility_tests.md
@@ -0,0 +1,120 @@
+# macOS 兼容性部署测试用例
+
+本文档记录了在 macOS (Darwin) 环境下进行 `setup-ai-workspace-all-in-one.sh` 全自动部署时遇到的跨平台兼容性问题及修复方案。
+
+## 核心背景
+
+原脚本和 Ansible Playbooks 是为 Debian/Ubuntu Linux 设计的，强依赖 `root` 权限、`apt` 包管理器、系统目录（`/usr/local/sbin`、`/etc/systemd`）及默认用户路径（`/home/ubuntu`）。在 macOS 无提权模式下部署，触发了大量权限与路径异常。
+
+---
+
+## TC-MAC-001: TTYD 二进制与路径异常
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `setup-ai-workspace-all-in-one.sh` |
+| **触发报错** | 脚本尝试下载 ttyd 二进制写入 `/usr/local/bin/ttyd`，无权限且架构不匹配 |
+| **修复方案** | Darwin 下拦截二进制下载，改用 `brew install ttyd`；使用 `command -v ttyd` 动态解析路径 |
+
+## TC-MAC-002: 全局提权 (Sudo) 阻塞
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `setup-ai-workspace-all-in-one.sh` → Ansible Playbook |
+| **触发报错** | `sudo: a password is required` |
+| **修复方案** | Darwin 下注入 `--extra-vars "ansible_become=false"` 取消自动提权 |
+
+## TC-MAC-003: 默认用户组分配失败
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `setup-xworkspace-console.yaml` |
+| **触发报错** | `chown` 找不到 `ubuntu` 组 |
+| **修复方案** | 条件渲染：`"{{ 'staff' if ansible_os_family == 'Darwin' else 'ubuntu' }}"` |
+
+## TC-MAC-004: 写死绝对路径 (Hardcoded Paths)
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `setup-xworkspace-console.yaml` 头部变量区 |
+| **触发报错** | `cd /home/ubuntu/xworkspace-console/dashboard: No such file or directory` |
+| **修复方案** | 将 `xworkspace_console_home` 重构为 `{{ ansible_env.HOME }}`, 所有派生目录链式求值 |
+
+## TC-MAC-005: 模板引擎渲染异常 (Undefined Variable)
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `console.plist.j2` |
+| **触发报错** | `AnsibleUndefinedVariable: 'nodejs_version' is undefined` |
+| **修复方案** | 移除 NVM 环境初始化和 `nodejs_version` 依赖，直接追加 `/opt/homebrew/bin` 至 PATH |
+
+## TC-MAC-006: NPM 全局助手脚本安装拒绝
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `roles/ai_agent_runtime/tasks/nodejs.yml` |
+| **触发报错** | `chown failed: [Errno 1] Operation not permitted: '/usr/local/sbin/...'` |
+| **修复方案** | macOS 下安装路径降级至 `~/.local/bin`，前置创建目录，关闭 `become` |
+
+## TC-MAC-007: Playwright 硬编码关联调用失败
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `roles/ai_agent_runtime/tasks/nodejs.yml` |
+| **触发报错** | `[Errno 13] Permission denied: '/usr/local/sbin/ai-workspace-manage-npm-global-package'` |
+| **修复方案** | 所有 `cmd` 中统一使用条件路径语句 |
+
+## TC-MAC-008: Apt 浏览器安装崩溃
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `roles/ai_agent_runtime/tasks/browser.yml` |
+| **触发报错** | `[Errno 2] No such file or directory: b'update'`（macOS 无 apt） |
+| **修复方案** | 增加 `when: ansible_os_family != 'Darwin'`；补充 macOS Chrome 探测路径；环境变量脚本路径改为用户目录 |
+
+## TC-MAC-009: Playwright 环境变量挂载目录缺失
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `roles/ai_agent_runtime/tasks/browser.yml` |
+| **触发报错** | `Destination directory ~/.local/state/ai-workspace/env does not exist` |
+| **修复方案** | 前置创建 env 目录；变量增加 `default(ansible_env.HOME)` 容错 |
+
+## TC-MAC-010: Agent Skills 角色硬编码路径与用户
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `roles/agent_skills/defaults/main.yml`、`roles/agent_skills/tasks/main.yml` |
+| **触发报错** | `[Errno 45] Operation not supported: b'/home/ubuntu'` |
+| **修复方案** | defaults 全部改为 `ansible_env.USER/HOME`；apt rsync 安装增加 Darwin 跳过 |
+
+## TC-MAC-011: Chromium 版本检查路径含空格
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `roles/ai_agent_runtime/tasks/verify.yml` |
+| **触发报错** | `No such file or directory: b'/Applications/Google'`（路径含空格被拆分） |
+| **修复方案** | `ansible.builtin.command` 改用 `argv` 列表形式传参，避免空格截断 |
+
+## TC-MAC-012: XWorkMate Bridge 基础目录写入系统路径被拒
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `setup-ai-workspace-all-in-one.sh` → `roles/vhosts/xworkmate_bridge`（变量 `xworkmate_bridge_base_dir`） |
+| **触发报错** | `TASK [roles/vhosts/xworkmate_bridge/ : Ensure xworkmate-bridge base directory exists]` → `There was an issue creating /opt/cloud-neutral as requested: [Errno 13] Permission denied: b'/opt/cloud-neutral'` |
+| **根因** | `xworkmate_bridge_base_dir` 默认硬编码为 `/opt/cloud-neutral/xworkmate-bridge`，macOS 以 `ansible_become=false` 运行，无权写入 `/opt`。该 base dir 同时被 `config.yaml`、launchd plist 的 `WorkingDirectory` 引用 |
+| **修复方案** | 沿用既有 macOS 适配约定（`gateway_openclaw_home`、`agent_skills_home` 等均在脚本 Darwin 分支以 `-e` 重定向到 `$HOME`），在 `setup-ai-workspace-all-in-one.sh` 的 Darwin 分支注入 `-e xworkmate_bridge_base_dir=$HOME/.local/state/cloud-neutral/xworkmate-bridge`，无需改动独立的 playbooks 仓库即可在运行时覆盖默认值 |
+
+---
+
+## 修复维度总结
+
+| 维度 | 涉及用例 |
+|------|---------|
+| 组件获取方式替换 (brew vs binary) | TC-001 |
+| 权限收缩 (become: false) | TC-002, TC-006, TC-007, TC-008, TC-009 |
+| 用户组适配 (staff vs ubuntu) | TC-003, TC-010 |
+| 目录路径降级 ($HOME vs /home/ubuntu, /opt) | TC-004, TC-006, TC-009, TC-010, TC-012 |
+| 包管理器绕过 (skip apt on Darwin) | TC-008, TC-010 |
+| 模板变量解耦 (remove nvm/nodejs_version) | TC-005 |
+| 路径空格兼容 (argv vs string) | TC-011 |
diff --git a/docs/case/test_prompts.md b/docs/case/test_prompts.md
new file mode 100644
index 0000000..4c8ce38
--- /dev/null
+++ b/docs/case/test_prompts.md
@@ -0,0 +1,83 @@
+# 测试提示词模板
+
+本文档提供了用于测试 `setup-ai-workspace-all-in-one.sh` 的标准化提示词模板，可直接复制粘贴到终端执行。
+
+---
+
+## 1. 快速安装（一键部署）
+
+```bash
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -
+```
+
+## 2. 带 API Key 安装
+
+```bash
+export DEEPSEEK_API_KEY="<your-deepseek-api-key>"
+export NVIDIA_API_KEY="<your-nvidia-api-key>"
+export OLLAMA_API_KEY="<your-ollama-api-key>"
+
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -
+```
+
+## 3. 卸载（保留数据）
+
+```bash
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -s -- uninstall
+```
+
+## 4. 彻底卸载（清除所有数据）
+
+```bash
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -s -- uninstall --purge
+```
+
+## 5. 完整生命周期测试（卸载 → 重装）
+
+```bash
+# Step 1: 彻底卸载
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -s -- uninstall --purge
+
+# Step 2: 设置 API Keys
+export DEEPSEEK_API_KEY="<your-deepseek-api-key>"
+export NVIDIA_API_KEY="<your-nvidia-api-key>"
+export OLLAMA_API_KEY="<your-ollama-api-key>"
+
+# Step 3: 重新安装
+curl -sfL https://raw.githubusercontent.com/ai-workspace-lab/xworkspace-console/main/scripts/setup-ai-workspace-all-in-one.sh | bash -
+```
+
+## 6. 使用本地 Playbook 开发调试
+
+```bash
+export PLAYBOOK_DIR="/path/to/local/playbooks"
+export DEEPSEEK_API_KEY="<your-deepseek-api-key>"
+export NVIDIA_API_KEY="<your-nvidia-api-key>"
+export OLLAMA_API_KEY="<your-ollama-api-key>"
+
+bash /path/to/setup-ai-workspace-all-in-one.sh
+```
+
+> 设置 `PLAYBOOK_DIR` 后脚本会使用本地 Playbook 目录，而非从 Git 远端拉取，适合开发调试场景。
+
+---
+
+## 环境变量参考
+
+| 变量名 | 用途 | 必填 |
+|--------|------|:----:|
+| `DEEPSEEK_API_KEY` | DeepSeek 模型 API 密钥 | 可选 |
+| `NVIDIA_API_KEY` | NVIDIA NIM API 密钥 | 可选 |
+| `OLLAMA_API_KEY` | Ollama 服务 API 密钥 | 可选 |
+| `PLAYBOOK_DIR` | 本地 Playbook 目录路径（开发调试用） | 可选 |
+
+---
+
+## 支持平台
+
+| 平台 | 状态 |
+|------|:----:|
+| macOS (Apple Silicon / Intel) | ✅ 已测试 |
+| Debian 11/12 | ✅ 已测试 |
+| Ubuntu 22.04/24.04 | ✅ 已测试 |
+| 其他 Linux 发行版 | ⚠️ 未测试 |
diff --git a/scripts/setup-ai-workspace-all-in-one.sh b/scripts/setup-ai-workspace-all-in-one.sh
index 57f2c85..f964da5 100755
--- a/scripts/setup-ai-workspace-all-in-one.sh
+++ b/scripts/setup-ai-workspace-all-in-one.sh
@@ -1981,6 +1981,10 @@ if [ "$(detect_os)" = "darwin" ]; then
     ANSIBLE_EXTRA_VARS+=("-e" "gateway_openclaw_home=$HOME")
     ANSIBLE_EXTRA_VARS+=("-e" "gateway_openclaw_compile_cache_dir=$HOME/.cache/openclaw-compile-cache")
     ANSIBLE_EXTRA_VARS+=("-e" "gateway_openclaw_service_path=$DARWIN_SERVICE_PATH")
+    # XWorkMate Bridge writes its runtime data under a base dir that defaults to
+    # /opt/cloud-neutral on Linux. macOS runs become=false, so /opt is not
+    # writable; relocate the bridge base dir under the user's home instead.
+    ANSIBLE_EXTRA_VARS+=("-e" "xworkmate_bridge_base_dir=$HOME/.local/state/cloud-neutral/xworkmate-bridge")
 else
     LINUX_CONSOLE_USER="$(linux_default_console_user)"
     LINUX_CONSOLE_HOME="$(linux_default_console_home "$LINUX_CONSOLE_USER")"