从 Windows 主力机切换到 Mac Studio（macOS）的影响评估

对照 harness 现有资产，梳理工作流、技术栈、配置与教学科研任务

macOS
Windows
工作流
Quarto
R
Author

胡华平

Published

October 23, 2026

摘要

本文对照 harness 仓库里已经落地的脚本、清单与说明，评估把日常主力机从 Windows 11 换成一台运行 macOS 的 Mac Studio（计划中的 M5 Max） 之后，哪些工作可以原样继续，哪些必须改路径或换工具。评估对象是本仓库已经写明的场景：R 与 Quarto 书稿和课件、Cursor 与 Positron、PowerShell 分发、Robocopy 镜像、中文 Word 书稿、Docker Selenium，以及 Cursor Cloud（Ubuntu）并行开发。本文不修改这些资产，也不推测尚未在本仓库验证的芯片参数。

核心结论：

  1. 学科内容与大部分课件、书稿源文件可以换机器继续写。 R 脚本、Lua 滤镜、MathJax / remark 静态资源、YAML 片段、Quarto 网站源和 GitHub Actions 都不绑定 Windows。Cloud Agent 今天已经在 Ubuntu 上跑，和 macOS 的用户态比和 Windows 更接近。
  2. 真正绑在 Windows 上的是「把资产装进业务项目」和「把渲染结果镜像到上传目录」这两条日常链路。 Install-Harness.ps1 的说明写明只在 Windows 路径语义下测试；copy-post-sync.R 直接调用 robocopy /MIR。这两处在 macOS 上不能当成已可用。
  3. IDE、字体、Word 目视、代理和 Docker 镜像架构要重配，但不必推倒重来。 settings.json 里的编辑器、Quarto、LaTeX 偏好可以保留；R 可执行文件、终端配置和用户设置目录必须按 macOS 另写。出版社接受的 docx 仍建议在 Windows 版 Word 上做目视验收。
  4. 过渡期应保留一台 Windows 电脑，至少覆盖一个教学周期。 它负责 PowerShell 分发脚本的验证、robocopy 镜像、v2rayN 文档中的网络排障，以及书稿在 Word 里的版式确认。Mac Studio 先承担写作、渲染、R 计算和 Cursor 本地代理。
flowchart TB
  subgraph keep ["沿用：源文件与云端"]
    A["R / Lua / YAML / MathJax"]
    B["Quarto 渲染与 GitHub Actions"]
    C["Cloud Agent（Ubuntu）"]
  end
  subgraph adapt ["重配：本机环境"]
    D["R 4.4 arm64 与 renv 库"]
    E["Cursor / Positron 路径键"]
    F["代理客户端、字体、Word"]
    G["Docker 镜像架构"]
  end
  subgraph block ["停用直至改写：Windows 专有链路"]
    H["Install-Harness.ps1"]
    I["robocopy 镜像"]
    J["v2rayN 与 %APPDATA% 分发"]
  end
  keep --> adapt
  adapt --> block

1. 评估范围

1.1 工作情景

维护者是统计学与计量经济学教师。当前主力机是 Windows。harness 的自我定位写在 AGENTS.md 与仓库规则里：集中管理可复用的工程配置、环境脚本和代码片段，面向 R、Quarto、JavaScript、PowerShell、Windows 11。业务上已经形成这些习惯：

情景 仓库中的落点
课程幻灯片：联网稿与教室离线包 docs/xaringan-dual-workflow.qmd、js/xaringan-dual/、js/mathjax-xaringan/
网站与 Reveal 的离线公式 docs/mathjax-quarto-assets.qmd、js/mathjax-quarto/
中文书稿 Word（图题、表题、横向页） docs/quarto-docx-chinese-book.qmd、scripts/quarto-docx/
渲染结果镜像到 Resilio Sync 的 staging docs/quarto-book-robocopy-mirror.qmd、scripts/quarto-sync/
把上述资产装进任意课程仓库 docs/install-harness.qmd、scripts/powershell/deploy-manifest.json
Cursor 写代码，Positron 做 R Console ide/cursor-settings/、ide/positron/
本机 Agent 与 Cloud Agent 并行 docs/cursor-local-cloud-parallel-dev.qmd
访问 GitHub 时的本机代理 docs/cursor-ide-v2rayn-network-guide.qmd
偶发的浏览器自动化（如实验提交抓取） docs/cursor-docker-selenium-workflow.qmd
harness 站点自身发布 docs/cloudflare-pages-deploy.qmd，构建机是 Ubuntu

scripts/r/ 与 scripts/sql/ 目前只有目录说明，没有绑操作系统的脚本。RStudio 目录同样是占位。本文不把尚未入库的 Stata、EViews 或 MATLAB 工程算进迁移成本；若科研主路径在那些软件上，许可证与 macOS 版本需要单独核对。

1.2 目标机器按什么来理解

目标是一台 Mac Studio，操作系统是 macOS，芯片是用户计划中的 Apple Silicon M5 Max。下文只用本仓库能够核对、且对 Apple Silicon Mac 稳定成立的事实：

  • 用户态是 Unix：默认 shell 为 zsh，路径用 /，没有盘符，没有 robocopy，没有 Windows PowerShell 5.1。
  • 进程与容器是 arm64。CRAN 与 Quarto 都提供 Apple Silicon 构建；只发布 linux/amd64 的容器要经模拟运行。
  • 内存是统一内存，CPU、GPU 与容器共享同一池，不存在本仓库所依赖的 NVIDIA CUDA 路径。当前资产没有 CUDA 步骤。
  • 具体核心数、内存容量与是否已经上市，以购买时的官方规格为准。本文不据此改工作流设计。

Mac Studio 是台式机。教室里的投影机、学生机和出差笔记本如果仍是 Windows，制作端换成 macOS 不会改变学生端打开的 HTML。离线课件包仍是交付物。

2. 资产分层

对照 deploy-manifest.json 的 profile，以及没有放进清单、但日常会用到的本机脚本，影响分成三层。

层 含义 换机后的动作
沿用 文件内容不调用 Windows 程序，渲染结果与操作系统无关 git clone 后继续用
重配 逻辑可保留，本机路径、字体、壳或镜像架构要改 改本机设置或补一份 macOS 入口，先不要覆盖仓库里的 Windows 键
停用直至改写 脚本假定 robocopy、%APPDATA%、盘符或 PowerShell 5.1 macOS 上不要执行；保留 Windows 机验证

2.1 总表

资产 层 Windows 上今天怎么用 换到 macOS 之后
Quarto 书稿与网站 .qmd、Lua 滤镜 沿用 quarto render，滤镜在 Pandoc 里跑 同一命令。Quarto 用 macOS arm64 安装包，版本仍守住文档里的 1.8+（已验证 1.8.26 与 1.10.18）
js/mathjax-xaringan/、js/mathjax-quarto/runtime/、js/xaringan-dual/ 的 JS、CSS、字体、R 沿用 拷进课程仓库后由浏览器与 R 使用 文件本身可拷。安装命令今天是 Install-Harness.ps1
reference-doc.docx 与编号规则 重配 Lua 改 OpenXML；样式在 Windows Word 里看 滤镜仍会跑。字体替换与页脚关系 rId14 要在 Word for Mac 里重新目视；出版社若指定 Windows Word，终稿仍在 Windows 上打开一次
scripts/quarto-docx/test/scripts/*.sh 沿用 文档写明 Linux/Cloud 用 bash Mac 终端可跑 run-check-all.sh、run-book.sh、sync-mirror.sh。Windows 继续用对应 .ps1
copy-post-sync.R + mirror-book-sync.ps1 停用直至改写 post-render 调用 robocopy /MIR /XD macOS 没有 robocopy。在写出 rsync（或等价）实现并核对退出码之前，不要从 Mac 发布 _book_sync2
Install-Harness.ps1、deploy-manifest.json 停用直至改写 按 profile 复制到课程仓库 安装说明 §11 已写明：脚本只在 Windows 路径语义下测试；Linux/macOS 需改用 rsync 或只复制文本资产
Distribute-CursorSettings.ps1、Distribute-PositronSettings.ps1 停用直至改写 读写 %APPDATA%\Cursor\User 与 %APPDATA%\Positron\User macOS 用户设置在 ~/Library/Application Support/Cursor/User/ 与 Positron 的对应目录。现有脚本不会找对文件
ide/cursor-settings/settings.json 重配 r.rpath.windows、r.rterm.windows、terminal.integrated.defaultProfile.windows 指向 C:/Program Files/R/R-4.4.3/... 与 PowerShell 编辑器、Quarto、LaTeX 键可保留。另加 r.rpath.mac、r.rterm.mac 与 terminal.integrated.defaultProfile.osx。两套键可以写在同一份 JSON 里，VS Code 按操作系统读取
ide/positron/settings.json 重配 positron.r.interpreters.default 为 C:/Program Files/R/R-4.4.3/bin/x64/R.exe 改为本机 R 框架或 Homebrew 前缀下的 R。Packages 面板、Quarto 大纲等键可保留
.cursor/setup-worktree-unix.sh 沿用 与 Windows 脚本并列，由 worktrees.json 按 OS 路由 Mac 上 Cursor 创建 worktree 时应走这份 bash：复制 .Renviron、可选 renv::restore()、quarto check
.cursor/setup-worktree-windows.ps1 停用（在 Mac 上） Windows worktree 引导 留在仓库里给仍使用的 Windows 机。Mac 不会执行它
v2rayN 指南 停用直至改写 TUN、系统代理、PAC、WinHTTP、本地入站 10808 三层模型依赖 Windows 网络栈。Mac 需要另一份客户端说明，不能把该文的菜单项原样操作
Docker Compose Selenium 重配 Docker Desktop（常见为 WSL2）；就绪检查用 curl.exe；避开 Windows 保留端口 5901 Compose 文件可复制。确认镜像有 linux/arm64。调试端口策略可以保留 15900 / 17900。keyring 在 macOS 上走钥匙串
Cloudflare Pages 工作流 沿用 GitHub Actions 在 Ubuntu 上 quarto render 与本机操作系统无关
R 语言服务器排障记录 重配 根因是 renv 库目录名 windows 与 .Platform$pkgType（win.binary）不一致 文档写明其它 OS 的目录名可能不同，以实测为准。Mac 上对应层级通常是 macos。沿用文中的 Sys.glob 写法，不要手拼 pkgType

3. 工作流

3.1 一天里的写、渲、传

Windows 上一条已经文档化的书稿链路是：

flowchart LR
  Q["quarto render"] --> R["R/copy-post-sync.R"]
  R --> RB["robocopy /MIR"]
  RB --> S["_book_sync2"]
  S --> RS["Resilio Sync"]
  RS --> WEB["网站服务器"]

copy-post-sync.R 里和 macOS 冲突的部分是具体的：

  • 绝对路径用盘符正则 ^[A-Za-z]:[/\\] 或 UNC \\server\share 判断。macOS 绝对路径以 / 开头，会被当成相对项目根的路径，拼到错误位置。
  • normalizePath(..., winslash = "\\") 与大小写不敏感比较，是为 NTFS 写的。APFS 默认不区分大小写，但分隔符与大小写规则仍应改成 POSIX。
  • system2("robocopy", ...) 以及「退出码大于 7 才算失败」。rsync 的成功码是 0，不能沿用这张码表。
  • 排除目录 .sync（以及文档中的 .well-known、.rclone-cache）这个需求仍然成立。Resilio Sync 有 macOS 客户端，换的是镜像工具，不是上传产品。

在 Mac 上写出并试过替代实现之前，课程网站的发布应继续在 Windows 上执行 post-render，或者只在 Mac 上 quarto render、把 _book 拷回 Windows 再镜像。两套做法都要避免对 staging 做未经验证的删除同步。

harness 文档站自己的发布不走这条链路。它由 .github/workflows/deploy-cloudflare-pages.yml 在 Ubuntu 上构建，换电脑不影响。

3.2 把 harness 装进一门新课

今天的入口是仓库根目录的：

.\scripts\powershell\Install-Harness.ps1 `
  -InstallProfile quarto-sync,cursor `
  -ProjectRoot "D:\work\my-course"

清单里的 profile 与用途：

Profile 复制内容 macOS 上的文件能否用
quarto-sync copy-post-sync.R、mirror-book-sync.ps1、.Renviron.example、post-render 片段 R 与 YAML 片段可抄；.ps1 与 R 里的 robocopy 调用不能当生产路径
cursor ide/cursor-settings/settings.json → 项目 .vscode/settings.json JSON 可抄。其中的 r.rpath.windows 在 Mac 上不生效，需补 r.rpath.mac
quarto-docx / quarto-docx-book Lua、reference-doc.docx、滤镜 YAML 可抄。目视验收见 §5.2
mathjax-quarto vendor/mathjax/ 与 html-math-method 片段 运行时可抄。Reveal 模板要另跑 patch-reveal-template.ps1，该脚本标明兼容 Windows PowerShell 5.1 与 PowerShell 7
xaringan-dual remark、字体、render-slide.R、pack-offline.R、MathJax 2 配置 可抄。安装后仍要把 decks.example.csv 抄成 decks.csv
docker-selenium Compose 与 Tasks 片段 Compose 可抄，镜像架构要核对
all 只含 quarto-sync 与 cursor 与上两行相同，没有把 docx / MathJax 算进「全部」

PowerShell 7（pwsh）可以装在 macOS 上，.NET 的路径 API 也有一部分能跑。这不等于 Install-Harness.ps1 已经支持 macOS：脚本注释与 安装说明 都把测试范围限定在 Windows，并专门避开了 Windows PowerShell 5.1 的 Split-Path -Parent 与 -File 绑定问题。那些规避在 zsh 里没有对应物，也不证明脚本在 macOS 上复制 copy-tree 时行为正确。过渡期用 git 或 rsync 按清单逐项复制沿用层文件，并在复制记录里写明来源 commit。

本机用户设置的双向同步同样只覆盖 Windows。Distribute-CursorSettings.ps1 用 git diff 比较「本机用户 settings」和仓库备份，再按 -Apply 或 -ArchiveToHarness 覆盖其中一侧。在 Mac 上若误跑或手抄错目录，容易把 Windows 路径写进仓库，或把 Mac 路径覆盖到仍在使用的 Windows 配置。两边同时使用时，仓库里的 settings.json 应同时保留 r.rpath.windows 与 r.rpath.mac，由编辑器按 OS 选用。从 Mac 回写仓库前先看 diff，确认没有删掉 Windows 键。

符号链接的取舍也变了。分发机制说明 记录：Windows 上普通用户创建 symlink 常常要开开发人员模式或管理员权限，所以项目侧以复制为主。macOS 上用户目录内的 ln -s 通常可以直接用。即便如此，课程仓库仍建议继续复制进 Git，这样学生、助教和 Cloud Agent 克隆后不依赖你的 Mac 路径。符号链接只适合本机用户设置指向一份备份，而且 Mac 与 Windows 的用户设置路径不同，不能共用同一条链接。

3.3 Cursor Local、Worktree 与 Cloud

并行开发指南 把环境分成三档，其中一条硬限制是：PowerShell 脚本不要在 Cloud 的 Linux 虚拟机上测试。换成 Mac 之后，这条限制变成两台「不能拿来验证 .ps1」的机器（Mac 与 Cloud），验证仍要落在 Windows Local / Worktree。

Mac 上已经有对应入口，不必新写引导脚本：

文件 谁来跑
.cursor/worktrees.json 把 Windows 指到 setup-worktree-windows.ps1，把 Unix 指到 setup-worktree-unix.sh
.cursor/setup-worktree-unix.sh macOS 与 Linux：复制主 checkout 的 .Renviron，有 renv.lock 则 renv::restore()，然后 quarto check
.cursor/install-cloud.sh 只在 Cloud Ubuntu 上跑

因此：

  • 改 docs/*.qmd、Lua、MathJax 静态文件、R 钩子：Mac 本地可以完成，并用 quarto render 或资产测试沙盒验证。
  • 改 Install-Harness.ps1、mirror-book-sync.ps1、Distribute-*.ps1：在 Windows 上改、在 Windows 上跑。Mac 上只读。
  • Move to Local 仍要求会话是在同一台电脑上启动的。Windows 上开的 Cloud 任务不能在 Mac Studio 上 Move to Local，反过来也一样。跨机器继续用 PR 或 cursor.com/agents。
  • 指南里「低配硬件把重活交给 Cloud」的分工会变化。Mac Studio 的统一内存更适合本机同时开多个 R 会话、Quarto 渲染和容器；Cloud 仍然适合不占用书房机器的并行代理，以及必须在 Linux 上复现的检查。Worktree 数量上限仍按磁盘来设，不必因为换了芯片就放到默认的 25。

3.4 配置资产的验证

验证工作流 的顺序不变：在 test/ 里改镜像，L0 到 L1 通过后再晋升 canonical 文件。沙盒不通过 Install-Harness.ps1 分发。

资产 在 Mac 上怎么跑
js/mathjax-xaringan/test/ Rscript Rscript/test-wrap-display-math.R，再按模块跑 run-module.R。这些是 R 脚本
js/mathjax-quarto/test/ Rscript js/mathjax-quarto/test/Rscript/test-inventory.R。清点项包含 patch-reveal-template.ps1 这个文件在不在，不要求在 Mac 上执行它
scripts/quarto-docx/test/ 用已有的 run-check-all.sh。Python 用 python3；Windows 文档里的 py -3 是 Windows 启动器

有一条 Windows 专有的回归不能只在 Mac 上签字：MathJax 4 的说明记录，用 file:// 直接打开 HTML 时，若脚本地址把盘符冒号编成 %3A，Chrome 不会把它当成 D:\...。macOS 的 file:///Users/... 没有盘符，在 Mac 上预览通过，并不覆盖这条 Windows 缺陷。教室电脑若仍是 Windows，这条检查留在 Windows 浏览器里做。

4. 技术栈

4.1 R、renv 与语言服务器

仓库备份把默认 R 固定在 4.4.3，路径是 C:/Program Files/R/R-4.4.3/bin/x64/R.exe。Mac 上应安装 同一小版本的 arm64 构建（CRAN 的 R.framework，或与该版本对齐的 Homebrew），避免 renv.lock 里已经锁定的二进制包在 4.5 上整库重装。恢复依赖时用：

Rscript -e "renv::restore(prompt = FALSE)"

需要编译的包还要本机的 Command Line Tools。数据框、固定效应和 Quarto 计算常用的 CRAN 包多数已有 arm64 二进制；锁文件里若出现只有源码包、且依赖 Fortran 的项，再补 gfortran。这是恢复时才会看见的清单，不是换机前能从本仓库完整列出来的。

语言服务器超时那篇排障记录 的机制在 Mac 上仍然成立：languageserver 用 callr 拉起子进程，默认大约 3 秒就绪；.Rprofile 若走完整 renv::activate() 再加 implicit snapshot，子进程会超时，Outline 会空。变的是目录名。Windows 案例里磁盘层级是 renv/library/windows/R-4.x/...，而 .Platform$pkgType 当时是 win.binary，手拼路径永远对不上。macOS 上中间一层一般是 macos，pkgType 也不会是 win.binary。把 Windows 那份错误 .Rprofile 原样拷过来，会在新系统上再次配错。记录里推荐的 Sys.glob / list.dirs 写法两边都能用。

ragg 与中文字体是另一件事。docx 说明把「Windows 默认 png() 加宋体得到空白图」明确划在滤镜之外，修法是 knitr 的 dev = "ragg_png"。Mac 上 Quartz / ragg 也不会自带名为「宋体」的字体；空白或方框时，应改用本机已安装的中文字体族，而不是把 Windows 字体文件名写进 chunk。

vscode-R 与 Positron 的分工可以保持：Cursor 配置 负责日常 Quarto 与 AI 辅助编辑；Positron 配置 负责 Console、Data Explorer 与 Notebook。两边都有 macOS 版本。Cursor 扩展仍来自 VS Code 市场；Positron 仍用 P3M / Open VSX，并且不要在 Positron 里安装 REditorSupport.r。RStudio 的片段目录在仓库里还是空的，换成 Mac 不增加也不减少这块资产。

终端默认配置今天是：

"terminal.integrated.defaultProfile.windows": "PowerShell"

Mac 上对应的是 terminal.integrated.defaultProfile.osx，日常用 zsh。仓库 settings.json 已把 files.eol 设为 \n。Windows 上若 Git 使用 core.autocrlf=true，换机后第一次提交可能把整文件标成换行变更。Mac 上宜使用 core.autocrlf=input，让工作区保持 LF，与这份设置一致。

4.2 Quarto、Pandoc 与 LaTeX

Quarto 在 macOS 上是独立安装包，Pandoc 仍随 Quarto 捆绑，不必为滤镜另装 Pandoc。quarto check 是 worktree 引导脚本里的冒烟命令，Mac 与 Windows 相同。

LaTeX Workshop 的设置没有写死 TeX 发行版路径，这份谨慎在换机时直接受益。Mac 上常用 MacTeX 或 TinyTeX；正向、反向搜索的 PDF 查看器要在新系统里重选，仓库备份没有绑定 Windows 的 SumatraPDF 路径。

4.3 壳、Python 与路径习惯

文档和脚本里的示例大量使用 D:\... 与 .\scripts\...。那些是调用说明，不是源文件里的业务逻辑。真正写进程序、会在 Mac 上算错的路径规则，集中在 copy-post-sync.R 的盘符判断（见 §3.1）。

Python 只出现在 docx 验收里：verify_docx.py 与 verify_book.py 是 python3 脚本；Windows 包装脚本优先找 py 启动器。Mac 上走已有的 shell 包装即可。

4.4 网络

v2rayN 指南 解决的是：Cursor 终端、扩展宿主、Git HTTPS 与 SSH 并不都认同一层代理；Windows 上还有 WinHTTP。文中的可复制实践是 harness 使用 HTTPS 远端，流量进 v2rayN 本地入站 10808，路由常用「绕过大陆」。

换成 macOS 之后，要重新确认的是三件事，而不是把 v2rayN 的界面找一遍：

  1. 本机代理客户端能否提供系统代理或 TUN，以及 Cursor 与 Git 实际走的是哪一条。
  2. HTTPS 远端是否仍指向本地 SOCKS/HTTP 入站；端口以新客户端为准，10808 只是 Windows 文档里的例子。
  3. SSH 远端（git@github.com）往往不走 PAC。若仍用 SSH URL，需要单独的 ProxyCommand 或改用 HTTPS。

校园网、图书馆数据库和只允许国内 IP 的站点，在「绕过大陆」一类规则下应保持直连。这是路由需求，与操作系统无关；实现该需求的软件要换。

4.5 Docker

Selenium 工作流的不变量在 Mac 上仍然适用：每个课程仓库一份 Compose；同一标签的镜像全机共用；同时只跑一个占用主机 5555 的服务；用完 down；RSelenium 1.7.9 与 CRAN selenium 不要混用镜像。账号仍放在 keyring，不写入仓库。macOS 上 keyring 使用钥匙串。

要改的是运行环境。Windows 文档假设 Docker Desktop，并提醒 不要把主机 5901 映射进去（该端口段在 Windows 上常被保留），调试口用 15900:5900，Selenium 4 的 noVNC 用 17900。Mac 上没有同一条 Windows 保留端口说明，但继续使用 15900 / 17900 可以让两台电脑的 Compose 保持一致。就绪检查在 Mac 上用 curl，不用 curl.exe。

Apple Silicon 上要先看镜像是否提供 linux/arm64。只有 amd64 时，Docker Desktop 会模拟运行，内存占用和启动时间都与在 Windows 的 WSL2 里跑原生 amd64 不同。Mac Studio 的统一内存同时供给 Chrome 容器、R 和编辑器，批次抓取时仍应「只开一个浏览器服务」。

4.6 硬件能分担什么

当前仓库里的重活是：多本 Quarto 书同时渲染、renv 恢复、若干 R 进程、偶尔一个 Chrome 容器，以及本机 Cursor Agent。这些都吃内存和单机持久运行，Mac Studio 的机箱形态和统一内存与这个用法相符。

本仓库没有 CUDA、也没有本地大模型训练步骤。若以后要在本机做依赖 NVIDIA GPU 的训练，Mac 提供的是 Metal，不能把现有 Windows 上的 CUDA 环境原样搬过来。这件事超出今天的资产范围，不应当成换机的前置条件。

5. 教学与科研任务

5.1 课件

xaringan 双工作流把同一套幻灯片做成联网稿和教室离线包。离线包带 remark、字体和 MathJax 配置，教室电脑没有外网时用浏览器打开本地 HTML。这些文件是静态资源加 R 打包脚本（render-slide.R、pack-offline.R），制作系统换成 macOS 之后，拷到 Windows 教室机上的压缩包仍然应能打开。

制作端要注意两件具体的事：

  • 新课仓库若依赖 xaringan-dual 或 mathjax-quarto profile，在 Mac 上还不能用 Install-Harness.ps1 一键安装，需要按清单复制（§3.2）。
  • patch-reveal-template.ps1 按 HTML 相对站点根的深度写入 reveal-template.html，并拒绝盘符、file:、http: 和反斜杠。深度规则在 Mac 上同样成立；在有 shell 替代脚本之前，这项补丁留在 Windows 上执行，或只把已经生成的 reveal-template.html 提交进课程仓库。

行内公式与 $$ 的配对钩子（mathjax-config.js 与 wrap-display-math.R）是文本，两边相同。remark 会吃掉 class 括号里反斜杠的问题也与操作系统无关，幻灯片写法不用因为换机而改。

5.2 中文书稿与出版社

滤镜解决的是 Quarto 默认 docx 不被出版社接受的版式：网站剖面的「图2- 13」、book 剖面的「图 3.1」、题注被包进 1×1 表、短列被压得折行、横向表多出空白页。这些由 Lua 和参考文档完成，Pandoc 在 macOS 上会执行同一套滤镜。

验收分两层：

层 今天的状态 Mac 上
结构 verify_docx.py / verify_book.py 检查 图N-M、横向页、空分节符等 用 run-check-all.sh 即可，作为换机后的第一道门禁
目视 说明写明：2026-10-15 的复测没有在 Word 里重看列宽和五号表头 Word for Mac 的中文字体替换（参考文档若使用仅随 Windows 提供的字体名）会让这一层更不可省略

book 剖面的横向页依赖参考文档里的页脚关系，默认 rId14，可用元数据 docx-landscape-footer 覆盖。换用 Mac 上另存的参考文档时，这个 id 可能变化，要以新文件为准，而不是假定 Windows 那份 docx 的关系 id 永远有效。

若出版社或学校模板规定用 Windows 版 Word 打开，终稿在提交前用保留的 Windows 电脑打开一次。结构脚本通过不能代替这次打开。

5.3 课程网站与数据作业

Resilio 同步的是 staging 目录。Mac 版 Resilio 可以继续承担上传；镜像必须先有 macOS 实现，否则 staging 里会重新堆积「删不掉的旧 HTML」，或误删 .sync。这是 Robocopy 镜像说明 开头就在解决的问题。

实验或成绩页面的偶发抓取可以迁到 Mac 上的 Docker，前提是镜像架构与钥匙串里的账号都重新确认过。选择器、登录权限和「不用 Cursor 内置浏览器当批次爬虫」这些约束不变。

SQL 目录还没有可执行资产。数据库客户端换成 macOS 版本即可，连接串与查询模板不因操作系统改变。面板数据脚本若写在 R 里，随 §4.1 的 renv 恢复走。

5.4 科研计算与可重复性

对合作者和 Cloud Agent 而言，可重复的部分是 Git 里的 .qmd、renv.lock、Lua 和 YAML，不是你本机的 C:/Program Files/R/...。换机是把这件已经在 Cloud Ubuntu 上成立的事，再在本地做成一次：锁文件保持跨平台写法，绝对路径留在不提交的 .Renviron。

Windows 与 Mac 的 renv 库目录不能互相复制。每台机器自己 renv::restore()。不要把 renv/library/ 打进同步盘。

同一学期若两台电脑都改 harness，避免把「只在一个操作系统上为真」的路径提交成唯一配置。用户级设置的归档尤其如此（§3.2）。

6. 建议的切换顺序

下面按依赖排列。前一项未核对，不要开始依赖它的教学发布。

  1. 保留 Windows 主力机一个教学周期。 在此期间它是 .ps1、robocopy、v2rayN 与 Word 目视的唯一验收机。
  2. 在 Mac Studio 上安装 arm64 的 R 4.4.3、Quarto、Git、Cursor、Positron、Docker Desktop、Word、Resilio，以及一套 macOS 代理客户端。 打开终端后 quarto check 与 Rscript -e "R.version$platform" 应显示 aarch64 / arm64。
  3. 克隆仓库，配置 Git 使用 LF，恢复 renv。 跑一次 MathJax 的 L0 与 docx 的 run-check-all.sh，确认沿用层在 Mac 上是绿的。
  4. 给 Cursor / Positron 补 macOS 路径键，不要删除 Windows 键。 用户设置目录用「应用程序支持」下的 User/settings.json，不要运行现有的 Distribute-*.ps1。
  5. 用 Unix worktree 脚本开一个 Cursor worktree，确认 .Renviron 被复制且 quarto check 通过。Cloud 任务按原指南继续；不要在 Mac 上测试 PowerShell 脚本。
  6. 课程仓库的安装改为按清单手工复制沿用层（Lua、MathJax 运行时、YAML、xaringan 的 R 与静态文件），直到存在经 macOS 测试的安装脚本。
  7. 为镜像另写实现并在副本目录上试删除语义，确认 .sync 仍在、源目录里已删除的 HTML 不会留在 staging。未完成这一步时，网站发布仍从 Windows 执行。
  8. 用 Word for Mac 打开一本已通过结构脚本的书稿，看「表题」「图题」、五号表头和横向页。与出版社模板不一致时，终稿改回 Windows Word 导出。
  9. 代理稳定之后再把 GitHub 推送改到 Mac 上日常进行。 先用 HTTPS 远端验证，再决定要不要保留 SSH。
  10. Windows 机降为验收机，而不是在 Mac 工作流未写进 docs/ 之前拆掉。新的 macOS 安装脚本、rsync 镜像和代理说明应各写一篇专题文档，并按仓库规则放进 docs/，而不是只改本篇的结论。
flowchart TB
  W["Windows 继续负责 ps1、robocopy、Word 目视、v2rayN"]
  M1["Mac：工具链与 renv"]
  M2["Mac：沿用层测试变绿"]
  M3["Mac：设置键与 worktree"]
  M4["Mac：课程仓库手工安装"]
  M5["镜像替代通过后再从 Mac 发布网站"]
  W --- M1
  M1 --> M2 --> M3 --> M4 --> M5

7. 边界

  • 本文是影响评估，不提供 Install-Harness 的 macOS 移植，也不把 robocopy 调用改写成 rsync。那两项要单独实现，并在 Windows 与 macOS 上各做一次不会误删 staging 的试验。
  • 未核对接线后的 M5 Max 核心数、统一内存容量和散热。工作流建议不依赖这些数字。
  • 未把 Stata、EViews、MATLAB 或只在校园 Windows 机房提供的软件算进「可以换」的清单。
  • 教室学生机、投影环境和出版社 Word 版本若仍是 Windows，交付物要在那些环境里打开一次。Mac 上的预览覆盖不了 file:// 盘符编码和 Windows 字体名这两类问题。
  • 现有 Windows 专题文档应保留。它们描述的是仍将存在的验收环境，不是过时说明。