merge-branch-mac

合并到 mac 分支

你负责 mac 分支。开发优先在 Windows（和 Android）上进行；macOS 和 iOS 随后通过 mac 分支接收这些工作。传入分支包含 Windows 以及可能的 Android 更改，此次合并有两项任务：引入这些更改，并确保追赶清单内容准确——每项 Windows 行为要么能在 Mac 上运行，要么有一条记录说明目前尚不支持。

分支。 通常是 mac；使用项目指定的名称（有些项目称它为 mac-catch）。如果分支不存在，请说明情况并先征求确认，再创建它。合并方向几乎总是 <main> → mac，这也是 merge-branch 针对长期分支建议的方向规则：在 mac 侧解决并验证问题，将破坏性影响控制在该侧。

完整遵循 merge-branch——包括调查、原则审查、“绝不擅自做出产品决策”的规则、按意图解决冲突、验证以及提交规则。本技能会额外加入 mac 检查环节。

请先阅读

• 平台追赶跟踪文档。 CATCHUP.md（通常位于 docs/macos/）、平台矩阵，或项目原则指定的 Apple 工作跟踪位置。它记录了已有的待办事项、已知的平台差异、编号以及早前合并的状态。如果项目还维护另一份跟踪文档来记录桌面端与手机端的差异，那属于另一个维度——不要在那里添加平台事项。
• 项目的 macOS 文档（docs/macos/ 或类似目录——这些文档可能只存在于 mac 分支），包括任何发布、签名或更新操作手册。
• 按 merge-branch 调查流程，查看 git log --oneline mac..<main> 和 git diff --stat mac...<main>。记录待合并的提交数量：数百个提交的合并需要按领域逐项检查，而不是按提交逐个检查。

mac 翻译流程

对于每项传入的更改，都要问：这项更改在 Mac 上会怎样？ 重点检查那些本质上带有 Windows 特征的部分：

位置	当前的 Windows 方案	Mac 需要什么
数据、配置、缓存和日志位置	%APPDATA%、%LOCALAPPDATA%	~/Library/Application Support、Caches、Logs — 不要回退到 XDG；保留项目已有的任何覆盖变量
进程和 IPC	命名管道、CreateNamedPipeW、tasklist/taskkill	Unix 套接字、pkill，以及通过 cfg 接缝实现的相同协议
自动启动和托盘	注册表 Run 键、通知区域图标	登录项或启动代理；菜单栏项 — 绝不能悄无声息地丢失托盘操作
脚本和动词	.bat、PowerShell	POSIX 脚本，动词逐一对应；只有 .bat 才有、且没有 Shell 等效实现的行为都要列为一项
快捷键	直接检查 Ctrl	在“命令键”指代平台命令键时使用平台命令键（Cmd）；若确实需要 Ctrl，则不在此列，否则直接检查 Ctrl 就是一项发现
窗口装饰	自定义标题栏、.ico、合成器假设	交通灯按钮、全屏行为、.icns、Dock
文件	路径和文件名假设、文件监视、fsync 语义	不区分大小写但保留大小写的路径、FSEvents 行为、不使用保留名称
OS 版本和环境	cmd /C ver、控制台附加	sw_vers，无需附加 — 保留 Windows 路径 cfg(windows)
发布和更新	安装程序、Authenticode、原地替换文件	.dmg 中的 .app、codesign 和公证、具有相同回滚机制的整包替换
依赖项	共享 [dependencies] 中仅适用于 Windows 的 crate	[target.'cfg(target_os = "macos")'.dependencies] 条目，或一个接缝
测试	手动写出快捷键组合、路径和分隔符	使用平台的写法，或使用封装这些内容的辅助函数

每项更改的结论只有以下三种之一，并且必须在报告中明确说明：

• 原样适用。
• 需要 mac 接缝 — 通过 cfg、端口 trait、平台适配器实现 — 在此次合并中完成，或在跟踪器中记录一项，说明要做什么以及在哪里做。
• 有意延期 — 在跟踪器中记录一项，说明原因以及触发后续处理的条件。

在 Mac 上绝不能悄无声息地不执行任何操作。

• 将机制下沉。 如果更改在共享代码中硬编码了 Windows 机制，而此处本应设置平台接缝，那么这应作为源分支的一项发现 — 修复应在源分支中进行 — 而不是在 Mac 侧打补丁，让这一泄漏继续存在。
• 带有 Android 特征的更改通常对应 iOS，而非 macOS；请将它们记入 iOS 后续跟进事项，不要强行纳入此次合并。
• 当两个分支的条目都有编号时，跟踪器的编号会冲突。请在 mac 侧重新编号，并在合并提交中说明。
• 源分支可能已经在 Windows 方案旁写好了 mac 方案。 编译并测试它 — 合并时，应首次在 Mac 上运行此前从未在 Mac 上构建过的方案。

记录下来

将跟踪器更新作为合并的一部分，而不是事后再做：对于此次合并引入的每项 Windows 行为，都要记录哪些内容已适配、哪些需要 mac 侧工作及其所在位置，以及哪些内容延期 — 每条延期记录都要提供足够的背景，让其他人拿到后即可着手处理。如果合并后仍有 Windows 行为在 Mac 上缺失，却没有对应记录说明，这次合并就尚未完成。

合并提交信息也要简要概述相同内容：引入了什么、mac 侧付出了什么代价，以及跟踪器中新增或关闭了哪些条目 — 此外，还要包含合并分支原本就要求记录的决策。

验证

• 构建并测试 mac 目标，而不只是主机目标。在 Windows 机器上，cargo check --target aarch64-apple-darwin（如果已安装该目标）可以对纯 Rust crate 进行类型检查，但无法链接或运行应用；如果项目有 macOS CI 任务，则以该任务作为构建和测试的最终依据。
• 在报告中明确说明每个目标的实际状态——已通过类型检查、已构建、已执行（仅限有人在 Mac 上运行的情况）——并说明这台机器无法验证的内容，而不要暗示验证已通过。
• 除非有人要求，否则不要推送。