更新经验清单，新增2026-03-10团队架构/运维约定，最后更新日期调整至2026-03-10。
This commit is contained in:
Alex-larget
77
.cursor/agent/团队/evolution/2026-03-10.md
Normal file
77
.cursor/agent/团队/evolution/2026-03-10.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# 团队共享 经验记录 - 2026-03-10
|
||||
|
||||
## 在 Windows 上一键启动 macOS 虚拟机（“龙虾”智能体经验）
|
||||
|
||||
### 场景 / 问题
|
||||
|
||||
- 成员希望在 **Windows 10/11** 上通过 **Docker** 一键安装 macOS，用于演示 / 测试。
|
||||
- 实际上：
|
||||
- **macOS 不能在 Docker 中运行**（Docker 只跑 Linux 容器，没有合法的 macOS 镜像）。
|
||||
- 唯一可行路径是：**WSL2 + Ubuntu + QEMU/KVM + OneClick-macOS-Simple-KVM**。
|
||||
|
||||
### 关键决策
|
||||
|
||||
1. **明确技术与法律边界**
|
||||
- 不支持也不承诺在 Docker 中直接跑 macOS。
|
||||
- 统一采用「**WSL2 + QEMU/KVM + OneClick**」这个方案，仅用于演示 / 测试。
|
||||
|
||||
2. **固定目录与流程约定**
|
||||
- Windows 侧统一放在：`C:\Users\{USERNAME}\Mycontent\macos-vm`
|
||||
- WSL 侧路径：`/mnt/c/Users/{USERNAME}/Mycontent/macos-vm`
|
||||
- 内部结构：
|
||||
- `OneClick-macOS-Simple-KVM/`
|
||||
- `BaseSystem.dmg` / `BaseSystem.img`
|
||||
- `macOS.qcow2`
|
||||
|
||||
3. **获取 OneClick 源码时优先走 zip，而不是 git clone**
|
||||
- 直接 `git clone` 很容易在国内网络环境下触发 `GnuTLS recv error (-110)` 等 TLS 超时。
|
||||
- 统一约定使用：
|
||||
- `https://codeload.github.com/notAperson535/OneClick-macOS-Simple-KVM/zip/refs/heads/master`
|
||||
- 然后在 WSL 中：
|
||||
- `curl + unzip` → 解压 → 重命名为 `OneClick-macOS-Simple-KVM`。
|
||||
|
||||
4. **依赖安装与 KVM 检查**
|
||||
- 在 Ubuntu-24.04 内安装：
|
||||
- `qemu-system qemu-utils python3 python3-pip cpu-checker`
|
||||
- 使用 `kvm-ok` 检查：
|
||||
- 期望输出：`/dev/kvm exists` + `KVM acceleration can be used`。
|
||||
- 若 `nested` 为 `N` 且需要嵌套虚拟化，使用 `.wslconfig` 打开 nested。
|
||||
|
||||
5. **下载 macOS Ventura 恢复镜像并生成 BaseSystem.img**
|
||||
- 通过 `python3 fetch-macOS-v2.py -s ventura` 下载官方 Recovery 镜像。
|
||||
- 将 `RecoveryImage.dmg` 重命名为 `BaseSystem.dmg`，再用 `qemu-img convert` 生成 `BaseSystem.img`。
|
||||
- 验收标准：
|
||||
- `BaseSystem.dmg` ≈ 678 MB
|
||||
- `BaseSystem.img` ≈ 3.0 GB
|
||||
|
||||
6. **以 HEADLESS + VNC 方式启动 VM**
|
||||
- 使用 `sudo HEADLESS=1 ./basic.sh` 启动 QEMU。
|
||||
- 在 Windows 中确认 `127.0.0.1:5900` 端口监听。
|
||||
- 统一告知使用 VNC 客户端连接 `localhost:5900`，再在图形界面内完成 macOS 安装向导。**用户环境已采用 TightVNC**，与 RealVNC Viewer 等方式等效。
|
||||
|
||||
7. **WSL 卡死与多 wsl 进程清理策略**
|
||||
- 当 `wsl --shutdown` 卡住、或者有大量 `wsl` 进程残留时：
|
||||
- 使用 PowerShell `Get-Process wsl | Stop-Process -Force` 清理。
|
||||
- 再执行 `wsl --shutdown` + `wsl -l -v` 验证状态恢复。
|
||||
|
||||
### 对应 Skill / 智能体
|
||||
|
||||
- 新建 Skill：`.cursor/skills/lobster-macos-vm/SKILL.md`
|
||||
- 技能名：`lobster-macos-vm`
|
||||
- 智能体名（对外）：**“龙虾”**
|
||||
- 职责：当用户在 Windows 上提出安装 / 维护 macOS 虚拟机的需求时，统一按该 Skill 流程执行：
|
||||
- 解释 Docker 不可用 → 切换到 WSL2 + QEMU 方案。
|
||||
- 固定目录 → 下载 OneClick → 安装依赖 → 下载 Ventura → 生成 `BaseSystem.img` → HEADLESS 启动 → 引导 VNC 安装。
|
||||
|
||||
- 计划脚本化：
|
||||
- 在 `开发文档/服务器管理/scripts/lobster_macos_vm.py` 中实现一键部署脚本，封装上述流程，供“龙虾”及人类成员复用。
|
||||
|
||||
### 用户环境补充
|
||||
|
||||
- **VNC 客户端**：当前环境使用 **TightVNC** 连接 `localhost:5900`，已写入龙虾 Skill，后续回复可一并推荐 TightVNC / RealVNC / TigerVNC 等。
|
||||
|
||||
### 适用角色
|
||||
|
||||
- 后端 / 运维：需要在本地或服务器上快速拉起 macOS VM 做兼容性验证或演示。
|
||||
- 团队：对外说明 **“我们不支持 Docker macOS，统一用龙虾方案”**。
|
||||
|
||||
@@ -25,6 +25,7 @@
|
||||
| 2026-02-27 | 小程序、团队 | 最佳实践 | SKILL-小程序开发 §6、SKILL-管理端开发 §4.1 | 输入框 padding 用 view/div 包裹 |
|
||||
| 2026-02-28 | 小程序、管理端 | 最佳实践 | miniprogram §6、admin §4.1 | input 边距口诀「外边包 view、内部 width 100%」；match 弹窗已修正 |
|
||||
| 2026-03-03 | 小程序 | 最佳实践 | miniprogram §8 | 我的页面卡片区边距 16rpx，个人中心类页面布局规范 |
|
||||
| 2026-03-10 | 团队 | 架构/运维约定 | lobster-macos-vm Skill | Windows 上统一使用 WSL2+QEMU+OneClick 的“龙虾”方案安装 macOS 虚拟机，禁止 Docker 直跑 macOS |
|
||||
|
||||
---
|
||||
|
||||
@@ -35,4 +36,4 @@
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：2026-03-03
|
||||
**最后更新**：2026-03-10
|
||||
|
||||
184
.cursor/skills/lobster-macos-vm/SKILL.md
Normal file
184
.cursor/skills/lobster-macos-vm/SKILL.md
Normal file
@@ -0,0 +1,184 @@
|
||||
---
|
||||
name: lobster-macos-vm
|
||||
description: Automates provisioning and troubleshooting of macOS virtual machines on Windows using WSL2, QEMU/KVM, and the OneClick-macOS-Simple-KVM project. Use when the user mentions 龙虾, macOS 虚拟机, 一键安装苹果系统 on Windows, or needs to re-deploy the Ventura/Sonoma VM.
|
||||
---
|
||||
|
||||
# 龙虾（lobster-macos-vm）
|
||||
|
||||
> 专门负责：在 **Windows 10/11** 上，通过 **WSL2 + Ubuntu + QEMU/KVM + OneClick-macOS-Simple-KVM** 自动拉起一台 macOS 虚拟机（Ventura 为默认），并处理常见网络 / WSL / KVM 问题。
|
||||
|
||||
## 触发场景
|
||||
|
||||
- 用户提到：**“龙虾”**、**“苹果系统虚拟机”**、**“Windows 上跑 macOS”**、**“一键安装 macOS 虚拟机”**
|
||||
- 用户需要：在 Windows 上**演示 / 测试** macOS，而不是 Docker 容器
|
||||
- 用户遇到：WSL 安装失败、`0x80072ee2` 网络错误、`kvm-ok`、`nested` 配置问题、`git clone` TLS 超时、OneClick 项目下载问题
|
||||
|
||||
## 核心能力
|
||||
|
||||
1. **环境检测与前置说明**
|
||||
- 明确告诉用户：**macOS 不能在 Docker 里运行，必须用 WSL2 + 虚拟机**。
|
||||
- 检查：
|
||||
- `wsl -l -v` → 是否有 `Ubuntu-24.04`，是否为 Version 2
|
||||
- `docker --version` 仅作背景信息，不作为必需条件
|
||||
- 若缺失 WSL2：
|
||||
- 指导用户在**管理员 PowerShell**中执行：
|
||||
- `wsl --install`
|
||||
- 重启后执行 `wsl --install -d Ubuntu-24.04 --web-download`（必要时）
|
||||
|
||||
2. **固定部署目录约定**
|
||||
- 所有与 macOS VM 相关的文件，统一放到：
|
||||
- Windows 路径：`C:\Users\{USERNAME}\Mycontent\macos-vm`
|
||||
- WSL 路径：`/mnt/c/Users/{USERNAME}/Mycontent/macos-vm`
|
||||
- 该目录下结构：
|
||||
- `OneClick-macOS-Simple-KVM/`（从 GitHub 下载的项目）
|
||||
- `BaseSystem.dmg` / `BaseSystem.img`
|
||||
- `macOS.qcow2`
|
||||
- 可能还有 `OneClick.zip` 等临时文件
|
||||
|
||||
3. **获取 OneClick 源码（优先 zip，退而求其次 git）**
|
||||
|
||||
优先使用 **codeload.zip**，避免长时间 `git clone` TLS 超时：
|
||||
|
||||
- 在 `macos-vm/` 目录内执行：
|
||||
|
||||
```bash
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y curl unzip
|
||||
rm -rf OneClick-macOS-Simple-KVM OneClick.zip
|
||||
curl -L --retry 8 --retry-delay 2 --connect-timeout 20 --max-time 600 \
|
||||
-o OneClick.zip \
|
||||
https://codeload.github.com/notAperson535/OneClick-macOS-Simple-KVM/zip/refs/heads/master
|
||||
unzip -q OneClick.zip
|
||||
mv OneClick-macOS-Simple-KVM-master OneClick-macOS-Simple-KVM
|
||||
```
|
||||
|
||||
仅当用户网络环境允许且确有需要时，才尝试：
|
||||
|
||||
```bash
|
||||
git clone --depth 1 https://github.com/notAperson535/OneClick-macOS-Simple-KVM.git
|
||||
```
|
||||
|
||||
出现 `GnuTLS recv error (-110)` 或 TLS 断开时，**不要重复 git clone**，改走 zip 方案。
|
||||
|
||||
4. **依赖安装与 KVM 检查**
|
||||
|
||||
在 `Ubuntu-24.04` 内执行：
|
||||
|
||||
```bash
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y qemu-system qemu-utils python3 python3-pip cpu-checker
|
||||
kvm-ok
|
||||
```
|
||||
|
||||
预期输出：
|
||||
|
||||
- `INFO: /dev/kvm exists`
|
||||
- `KVM acceleration can be used`
|
||||
|
||||
若 `nested` 为 `N` 但 `kvm-ok` 正常：
|
||||
|
||||
- 提示用户在 `C:\Users\{USERNAME}\.wslconfig` 中写入：
|
||||
|
||||
```ini
|
||||
[wsl2]
|
||||
nestedVirtualization=true
|
||||
kernel=C:\\Users\\{USERNAME}\\bzImage
|
||||
debugConsole=true
|
||||
pageReporting=true
|
||||
kernelCommandLine=intel_iommu=on iommu=pt kvm.ignore_msrs=1 kvm-intel.nested=1 kvm-intel.ept=1 kvm-intel.emulate_invalid_guest_state=0 kvm-intel.enable_shadow_vmcs=1 kvm-intel.enable_apicv=1
|
||||
```
|
||||
|
||||
并执行 `wsl --shutdown` 之后重试。
|
||||
|
||||
5. **下载 macOS Ventura 恢复镜像并生成 BaseSystem.img**
|
||||
|
||||
在 `OneClick-macOS-Simple-KVM` 目录内：
|
||||
|
||||
```bash
|
||||
cd /mnt/c/Users/{USERNAME}/Mycontent/macos-vm/OneClick-macOS-Simple-KVM
|
||||
chmod +x *.sh *.py
|
||||
[ -f macOS.qcow2 ] || qemu-img create -f qcow2 macOS.qcow2 64G
|
||||
python3 fetch-macOS-v2.py -s ventura
|
||||
[ -f RecoveryImage.dmg ] && mv RecoveryImage.dmg BaseSystem.dmg
|
||||
qemu-img convert BaseSystem.dmg -O raw BaseSystem.img
|
||||
ls -lah BaseSystem.* macOS.qcow2
|
||||
```
|
||||
|
||||
成功标志：
|
||||
|
||||
- `BaseSystem.dmg` ≈ 678 MB
|
||||
- `BaseSystem.img` ≈ 3.0 GB
|
||||
- `macOS.qcow2` 已存在（几十 KB 起步）
|
||||
|
||||
6. **启动虚拟机（headless + VNC: localhost:5900）**
|
||||
|
||||
在 `OneClick-macOS-Simple-KVM` 目录内执行：
|
||||
|
||||
```bash
|
||||
sudo HEADLESS=1 ./basic.sh
|
||||
```
|
||||
|
||||
常见日志：
|
||||
|
||||
- ALSA / audio 报错（没有声卡驱动）→ **可以忽略**
|
||||
- `BdsDxe: loading Boot0001 "UEFI QEMU HARDDISK QM00017"...` → 已经开始从虚拟硬盘启动
|
||||
|
||||
在 Windows 侧确认端口：
|
||||
|
||||
```powershell
|
||||
Get-NetTCPConnection -LocalPort 5900 -State Listen
|
||||
```
|
||||
|
||||
若监听正常，提示用户：
|
||||
|
||||
- 安装 VNC 客户端并连接 `localhost:5900`，进入 macOS 安装向导（磁盘工具抹盘 + 安装系统）。
|
||||
- **常用 VNC 客户端**：RealVNC Viewer、**TightVNC**（用户环境已采用）、TigerVNC 等均可，连接地址均为 `localhost:5900`。
|
||||
|
||||
7. **WSL / 网络故障排查**
|
||||
|
||||
- 若 `wsl` 进程过多、`wsl --shutdown` 卡死：
|
||||
- 在 PowerShell 中执行：
|
||||
|
||||
```powershell
|
||||
Get-Process -Name wsl -ErrorAction SilentlyContinue | Stop-Process -Force
|
||||
wsl --shutdown
|
||||
wsl -l -v
|
||||
```
|
||||
|
||||
- 若 `wsl --install` 报 `0x80072ee2` 或无法访问 `raw.githubusercontent.com`：
|
||||
- 提醒用户这是 **网络 / DNS 问题**，可尝试：
|
||||
- 切换 DNS 到 `8.8.8.8`
|
||||
- 使用合规代理 / VPN
|
||||
- 使用 `--web-download` 方式安装发行版：
|
||||
|
||||
```powershell
|
||||
wsl --install -d Ubuntu-24.04 --web-download
|
||||
```
|
||||
|
||||
8. **Python 一键脚本（lobster_macos_vm.py）协同**
|
||||
|
||||
当仓库中存在 `开发文档/服务器管理/scripts/lobster_macos_vm.py` 时：
|
||||
|
||||
- 优先引导用户在 **PowerShell** 中执行：
|
||||
|
||||
```powershell
|
||||
python C:\Users\{USERNAME}\Mycontent\macos-vm\lobster_macos_vm.py
|
||||
```
|
||||
|
||||
- 该脚本应负责：
|
||||
- 检查 / 安装 WSL2 + Ubuntu-24.04（必要时提示用户重启）
|
||||
- 确保 `C:\Users\{USERNAME}\Mycontent\macos-vm` 目录存在
|
||||
- 在 WSL 内下载 OneClick 源码 zip、解压到固定目录
|
||||
- 安装 QEMU / Python 依赖并检查 `kvm-ok`
|
||||
- 下载 Ventura 恢复镜像并生成 `BaseSystem.img`
|
||||
- 启动 `sudo HEADLESS=1 ./basic.sh`
|
||||
- 输出清晰的步骤说明（包括如何用 VNC 连接）
|
||||
|
||||
## 使用示例
|
||||
|
||||
- 用户说：「**龙虾，帮我在这台 Windows 上一键装一个 macOS 虚拟机，用来演示**」
|
||||
- 按上述步骤依次执行：环境检测 → 创建 `macos-vm` 目录 → 下载 OneClick → 安装依赖 → 下载 Ventura → 生成 `BaseSystem.img` → 启动虚拟机，并提醒用户用 VNC 连 `localhost:5900` 完成图形安装。
|
||||
|
||||
- 用户说：「**龙虾，之前的 macOS 虚拟机挂了，重装一遍**」
|
||||
- 复用相同目录和镜像文件，必要时重新下载 `BaseSystem.dmg`，再启动 `HEADLESS=1 ./basic.sh`。
|
||||
|
||||
Reference in New Issue
Block a user