fnvtk/soul-yongping
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
991e17698c48be92c4cf6cb5fca73ee283efffa7
soul-yongping/.cursor/agent/团队/evolution/2026-03-10.md
Alex-larget f2af615087 1
2026-03-10 20:53:52 +08:00

8.0 KiB
Raw Blame History

团队共享 经验记录 - 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 等。

安装完成与使用规范快照

  • 当前虚拟机参数：
    • 内存：8G（-m 8G）
    • CPU：1 颗 CPU × 4 核 × 2 线程（共 8 线程）
    • 系统盘：macOS.qcow2，逻辑容量 64G，可后续通过 qemu-img resize 扩容。
  • 启动方式快照：
    • 优先使用 C:\Users\{USERNAME}\Mycontent\macos-vm\一键启动-macOS虚拟机.bat
    • bat 内部做两件事：
      1. 启动 WSL → 进入 OneClick-macOS-Simple-KVM → sudo HEADLESS=1 ./basic.sh
      2. 等待约 10 秒后自动启动 TightVNC Viewer 连接 localhost:5900
    • 关闭规则：不要关名为「macOS 虚拟机 - 勿关此窗口」的终端窗口，否则虚拟机会被强制关闭。
  • 安装阶段经验：
    • 安装过程中多次重启属正常，出现 X86PlatformPlugin::systemWillShutdown! / IOPlatformHaltRestartAction -> AppleSMC 说明在正常关机/重启。
    • OpenCore 菜单的选择顺序：
      • 安装阶段：多次选择 macOS Installer 直至不再出现安装向导。
      • 安装完成：只选系统盘（如 Macintosh HD），不要选 mac - Data。
    • 安装完成后，为避免反复从恢复盘启动，basic.sh 默认不再挂载 BaseSystem.img；需要重装时可通过 INSTALL_MEDIA=1 HEADLESS=1 ./basic.sh 临时挂载。

适用角色

  • 后端 / 运维：需要在本地或服务器上快速拉起 macOS VM 做兼容性验证或演示。
  • 团队：对外说明 “我们不支持 Docker macOS，统一用龙虾方案”。

管理端迁移 Mycontent-temp：菜单/布局新规范基线

决议（团队共享）

  • 目标态基线：以 Mycontent-temp/soul-admin 的 AdminLayout + SettingsPage 作为“新规范基线”，后续管理端所有菜单/布局调整按该基线执行，避免两套后台并行发散。
  • 主导航收敛：侧栏只保留 5 个主入口（概览/内容/用户/找伙伴/推广），系统设置固定底部，取消“更多”折叠入口。
  • 功能不丢但入口收敛：订单/提现/推广设置/VIP角色/导师等页面保留路由可达，入口通过概览卡片或页面内跳转承载；作者/管理员设置并入 /settings?tab=author|admin。

实施建议

  • 迁移时优先保证：鉴权一致（GET /api/admin）、路由可达性、菜单一致性，再逐步优化概览聚合接口与快捷入口。

新旧版代码对比方法论（Mycontent-temp vs miniprogram）

场景

存在两个并行代码库（主线 + 预览版），需要判断哪个版本更可靠，以及如何安全地吸收另一版的优点。

最佳实践

  1. 批量 diff 优先于逐文件比较：用 PowerShell 批量对比 WXSS/JS/WXML 文件，精确列出「相同/有差异」的文件清单，再聚焦差异文件逐一分析。
  2. 以功能完整性为基准：不以「新/旧」日期判断优劣，而以功能是否完整为主要依据；本次判断旧版（miniprogram）才是功能更完整的版本。
  3. 差异归类：
    • 旧版有、新版没有 → 旧版是主线，保留旧版
    • 新版有、旧版没有 → 评估是否需要移植（如 dashboard-stats 调用）
    • 样式差异 → 对比具体行数，判断是改进还是遗漏
  4. 接口对比时对照新版参考修复 bug：新版的接口实现即使存在，也可能有遗漏；参考后自行修复（去重、最小值、错误码等）再提交。

适用场景

  • 分支合并前的功能完整性分析
  • 迁移预览版到主线时的取舍决策
  • 跨版本 bug 溯源

同时影响：小程序开发工程师、后端工程师 详见会议纪要：.cursor/meeting/2026-03-10_小程序新旧版对比与dashboard接口新增.md

Toast 通知系统 & DB 变更 SOP（团队共享）

Toast 批量替换方法论

使用 PowerShell 正则脚本批量替换 alert → toast，替换后必须人工复查 toast.info()：

  • 验证提示类（"请输入/请填写/密码至少/ID已存在"）被脚本误判为 info，应改为 error
  • 核查方式：grep -r "toast.info(" src/ 逐条确认语义

DB 变更 SOP（前后端联动）

当前端新增字段时，完整变更流程：

步骤 执行方 操作
1 后端 执行 ALTER TABLE 或用 db-exec 脚本
2 后端 更新 internal/model/*.go struct
3 后端 重启服务验证
4 管理端 确认保存请求不再报 1054

若跳过任一步骤，GORM 写入时必报 Unknown column。

同时影响：管理端开发工程师、后端工程师 详见会议纪要：.cursor/meeting/2026-03-10_Toast通知系统全局落地.md