From d094c27b862619084dfa69f3343240a122ec0d78 Mon Sep 17 00:00:00 2001
From: Haitao Pan <haitaopanhq@gmail.com>
Date: Thu, 18 Jun 2026 11:03:26 +0000
Subject: [PATCH] docs: add progress report for TC-MAC-012 (macOS bridge base
 dir fix)

---
 docs/report/TC-MAC-012-26-06-18-19.md | 61 +++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 docs/report/TC-MAC-012-26-06-18-19.md

diff --git a/docs/report/TC-MAC-012-26-06-18-19.md b/docs/report/TC-MAC-012-26-06-18-19.md
new file mode 100644
index 0000000..1787baf
--- /dev/null
+++ b/docs/report/TC-MAC-012-26-06-18-19.md
@@ -0,0 +1,61 @@
+# 进度报告 · TC-MAC-012
+
+| 项目 | 内容 |
+|------|------|
+| **用例编号** | TC-MAC-012 |
+| **报告时间** | 2026-06-18 19:00 (Asia/Shanghai) |
+| **关联提交** | `cf97344` fix: relocate xworkmate-bridge base dir under $HOME on macOS |
+| **平台** | macOS (Darwin) 本机部署 |
+| **状态** | ✅ 已修复并提交（待 Mac 端实跑复验） |
+
+## 1. 问题现象
+
+`curl -sfL .../setup-ai-workspace-all-in-one.sh | bash -` 在 macOS 本机部署时中断：
+
+```
+TASK [roles/vhosts/xworkmate_bridge/ : Ensure xworkmate-bridge base directory exists]
+fatal: [127.0.0.1]: FAILED! => {"changed": false,
+  "msg": "There was an issue creating /opt/cloud-neutral as requested:
+          [Errno 13] Permission denied: b'/opt/cloud-neutral'",
+  "path": "/opt/cloud-neutral/xworkmate-bridge"}
+PLAY RECAP
+127.0.0.1 : ok=145  changed=12  unreachable=0  failed=1  skipped=176
+```
+
+## 2. 根因分析
+
+- `roles/vhosts/xworkmate_bridge/defaults/main.yml` 中 `xworkmate_bridge_base_dir` 硬编码为 `/opt/cloud-neutral/xworkmate-bridge`。
+- macOS 部署以 `ansible_become=false` 运行（见 TC-MAC-002），普通用户无权在 `/opt` 下创建目录，触发 `Errno 13`。
+- 该 base dir 同时被 `config.yaml`、launchd plist 的 `WorkingDirectory` 引用，因此必须指向用户可写路径。
+
+## 3. 修复方案
+
+沿用本仓库既有的 macOS 适配约定：不改动独立的 playbooks 仓库，而是在 `setup-ai-workspace-all-in-one.sh` 的 Darwin 分支以 `-e` 注入覆盖（与 `gateway_openclaw_home`、`agent_skills_home`、`xworkspace_console_root` 等同样处理）。
+
+```bash
+ANSIBLE_EXTRA_VARS+=("-e" "xworkmate_bridge_base_dir=$HOME/.local/state/cloud-neutral/xworkmate-bridge")
+```
+
+Ansible extra-vars 优先级高于 role defaults，因此对在线（`curl | bash`）与离线两种安装路径均生效；`config.yaml` 与 plist 的 `WorkingDirectory` 因派生自该变量而一并迁移。
+
+## 4. 验证情况
+
+- `bash -n` 语法检查通过。
+- 已确认提交内 `-e` 覆盖存在且行为正确（extra-vars 覆盖 role 默认值）。
+- 复核 bridge 角色其余系统路径，确认不会把失败下移：
+  - `xworkmate_bridge_binary_path` (`/usr/local/bin/...`) 仅 `stat` 读取，非写入。
+  - 所有 `/etc/systemd` 任务已带 `when: ansible_os_family != 'Darwin'` 守卫。
+  - `/etc/caddy` 相关任务与 `gateway_openclaw` 完全一致，而该角色已在本次 145 个 OK 任务中通过，说明该机器 `/etc/caddy` 可写。
+- 局限：当前环境无 Darwin 主机，未能实跑完整部署，验证基于变量优先级推导 + 路径审计。
+
+## 5. 交付物
+
+- `scripts/setup-ai-workspace-all-in-one.sh`：Darwin 分支新增 base dir 覆盖（+4 行）。
+- `docs/case/macos_compatibility_tests.md`：新增 TC-MAC-012 及修复维度总结更新。
+- `docs/case/{combination_tests,test_prompts}.md`：随提交纳入版本管理。
+
+## 6. 后续建议
+
+1. 在 Mac 上重跑 `COMBO-001` 验证 bridge 任务通过。
+2. 若下一阻塞点为 `/etc/caddy` 权限，可按同样方式（Darwin 守卫或 `-e` 重定向）处理。
+3. 未纳入本次提交：预先存在且无关的 `create-ai-workspace-offline-package.sh`（新增 `npm`）改动，以及生成的离线包目录。