维护者确认 · #2899 perf(ios-simulator): 构建链路优化

[MagicLizi]

确认类别

arch（iOS Simulator 构建管线重构）

触发原因

对 iOS Simulator MCP 集成的构建链路做了较大优化（arch 预检、缓存复用、回收），约 2000 行改动，属架构级变更。

需要维护者确认

1. 新构建链路的架构决策是否合理
2. 缓存策略与回收时机是否符合预期

如何放行

在 PR 上 Approve 即可；如需作者修改请 Request Changes。

---

关联 PR:#2899(作者 @BarneyZhaoooo);本 issue 由 review-pr 流程自动创建,用于先讨论该 PR 涉及的技术架构调整,维护者确认后 PR 会恢复推进。

[dash-s-cindy]

判断

跨会话复用 DerivedData/SPM、构建前架构预检和机会式缓存回收，能够直接改善同一 worktree 反复 build/run 的耗时、失败反馈和磁盘占用，整体架构方向值得继续推进。当前建议先 Request Changes，暂不直接 Approve：共享缓存的隔离维度基本合理，但“冷缓存”的判定依据、跨进程生命周期不变量和真实 Xcode 链路仍缺少足够证据。

行动

1. 将缓存淘汰依据改为显式的最后使用时间。 建议为每个 cache key 维护 lastUsed marker，并在构建准入和结束时更新；prune 读取 marker，而不是仅依赖 cache-key 目录的 mtime。
2. 补真实 Simulator/Xcode smoke 后再放行。 至少覆盖：
   • 普通 .xcodeproj 与 CocoaPods .xcworkspace；
   • SPM 有 Package.resolved 与首次无 resolved 文件两种情况；
   • scheme 包含 app、extension/test/helper 等多个 target；
   • arm64 匹配与明确不匹配；如团队仍支持 Intel Mac，再覆盖 x86_64；
   • 同一 worktree 连续两次构建，记录冷构建/增量构建耗时和缓存体积；
   • 缓存回收后重新构建、安装和启动均正常。
3. 把现有 profile 级 writer lease 固化为共享缓存的合并门禁。 增加双进程测试，证明共享同一 userData 时，只有持有 ownership-registry writer lease 的 Host 能执行 build、SPM checkout、prune 和 artifact 管理；另一进程必须在触碰缓存目录前返回 DEVICE_BUSY。同时验证持锁 Host 退出/停用时先终止并等待 active build，再释放 lease。
4. 收窄 SPM fallback 条件。 当前实现只要失败输出中出现 Package.resolved 就去掉 -onlyUsePackageVersionsFromResolvedFile 重试，可能让其他编译/解析失败重复执行一次昂贵构建。建议只匹配 Xcode 明确的“resolved file 缺失/不可用”诊断，并为“普通失败日志恰好提到 Package.resolved”增加不重试测试。
5. 由维护者明确确认 7 天策略的产品语义。 固定 TTL 可以作为简单的机会式回收策略，但它不是磁盘配额，也不能严格保证磁盘上限；如果目标只是回收长期不用的缓存，可以保留并准确表述。如果目标是防止磁盘持续增长，还需要另行确认是否增加总容量上限/LRU，这不应在缺少产品决策时默认扩入本 PR。

代码与历史证据

当前 main 尚未具备这些优化

在 main@a201619aebe71140d2c3ad40e5b45020553da75e：

• apps/desktop/src/main/mcp-integrations/ios-simulator.ts 的构建目录仍由 sha256(instanceId) 派生，属于实例/会话级隔离；尚无按 worktree、架构和 container 共享的 cache key，也没有对应的冷缓存 prune。
• packages/ios-simulator-runtime/src/project-adapter.ts 使用 generic/platform=iOS Simulator 构建；构建前不读取目标 app 的有效架构。
• 当前构建命令没有共享的 -clonedSourcePackagesDirPath，也没有 -onlyUsePackageVersionsFromResolvedFile 及 fallback。

因此，本 PR 是新增架构，不是对 main 中既有共享缓存实现的小修复。

PR 的隔离与产物生命周期设计总体合理

#2899 当前 HEAD 将缓存按 worktree、目标架构和 Xcode container 分隔，对同一 cache key 的构建做进程内串行；构建结果复制到不可变产物路径，并为 install/launch 等消费者增加 pin 和有界淘汰。测试覆盖了活动缓存跳过、原子 rename 后删除、产物淘汰顺序，以及 install/launch 期间不删除正在读取的产物。这些设计降低了不同项目互相污染、构建覆盖待安装产物和异步删除竞态的风险。

架构预检也选择可识别的 .app target，而不是盲目采用 -showBuildSettings -json 的第一项；无法可靠识别 app target 时跳过预检，避免 extension/test target 造成误拦截。这个 fail-open 边界比猜测依赖图更稳妥。

仅用目录 mtime 不能可靠表达“最后使用”

pruneStaleIOSSimulatorBuildCaches() 根据 cache-key 目录自身的 mtime 判断是否超过 7 天，并以活动 cache-key 集合保护正在构建的目录。活动保护和原子 rename 能避免删除当前正在写入的 key，但不能保证 mtime 代表最近一次使用：Xcode 通常写入 DerivedData/SPM 的后代目录，后代内容变化不必更新顶层 cache-key 目录的 mtime。

结果是，一个昨天仍成功增量构建、但顶层目录很久没有新增/删除直接子项的缓存，可能在今天由另一个 cache key 触发 prune 时被视为陈旧。它不会破坏用户源码，但会造成非预期全量重编，也使“7 天冷缓存”语义不准确。显式 marker 能让策略可测试、可解释，并避免依赖文件系统目录时间的间接行为。

跨进程安全依赖上层单 writer 不变量

packages/ios-simulator-runtime/src/ownership-registry-file.ts 已通过 Darwin O_EXLOCK 为每个 profile 提供内核持有的独占 writer lease。生产 Host 初始化只有取得该 lease 后才发布默认 Host；同一 userData 的第二个进程应以 DEVICE_BUSY 失败。因此，在当前产品模型下，没有必要立即再增加 cache-key 级跨进程锁。

但是，共享缓存把这个上层不变量变成了数据安全前提，而 #2899 的现有测试主要验证单进程内的 active-key、prune 和 artifact 生命周期。应增加多进程/双 Host 回归测试，确保未来 Host 初始化或释放流程调整时，不会让两个进程同时写同一 DerivedData/SPM cache。

真实链路仍未验证

PR 描述记录了 runtime 测试、Desktop 定向测试和 typecheck 通过，但同时明确说明尚未在真实用户项目上验证架构预检，也未在真实模拟器完成 build/install/launch 端到端。对于会改变 Xcode 参数、SPM 解析路径、缓存布局和产物生命周期的较大改动，单元测试不足以替代上述 smoke；特别是 -showBuildSettings 多 target 输出和无 Package.resolved 的实际错误文本，均受 Xcode/工程形态影响。

风险边界

• 这些缓存均位于 Cindy 管理目录，回收不会删除用户源码；主要风险是误回收导致全量重编、构建/安装竞态或错误的提前架构拒绝。
• 当前没有证据表明必须显式 pin 用户项目的架构，也没有产品意图支持修改 Podfile、Package.swift 或项目 build settings；本 PR 保持只读用户工程的方向是正确的。
• 固定 7 天 TTL 是待维护者确认的策略，不应表述为严格的磁盘上限。若暂不引入容量配额，应在代码注释和 PR 描述中称为“机会式冷缓存回收”。
• fix(ios-simulator): release disabled Host and settle WDA fallback #2494 正在改变 capability 停用后的 Host 和 writer lease 释放时机。若它先合并，perf(ios-simulator): 构建链路优化（arch 预检 + 缓存复用 + 回收） #2899 必须基于其最终生命周期重新验证；关键顺序是关闭新 build admission、终止并等待 active build、完成缓存/产物操作，最后才释放 writer lease。

建议验收标准

满足以下条件后，可以重新考虑 Approve：

• cache key 的最后使用时间由显式 marker 维护，并有“顶层目录 mtime 很旧、但 marker 很新时不得删除”的测试；
• SPM fallback 只针对明确的 resolved-file 缺失诊断；
• 真实 Xcode 项目完成 build → immutable artifact → install → launch smoke；
• 至少一组真实架构不匹配样本确认会在编译前返回 APP_ARCH_MISMATCH，匹配项目不会误拦截；
• 双进程共享 profile 测试证明非 writer Host 在任何缓存 I/O 前失败，并验证 writer 退出后的安全接管；
• 维护者明确接受“7 天机会式 TTL、暂无容量硬上限”的策略，或另行给出容量策略。

相关记录

• feat: iOS 模拟器构建链路优化（arch 预检 + 缓存复用 + 回收） #2891：本 PR 的直接需求来源，记录了按实例隔离导致重复构建、SPM 重复检查和磁盘增长问题；其中约 158GB 与 1–2 分钟数据目前来自提报样本，尚无仓库内独立复测。
• iOS 模拟器构建缓存的跨进程并发仲裁（dev+packaged 双开 / --passive 多开） #2919：讨论共享缓存的跨进程仲裁。进一步检查表明当前产品已有 profile 级 writer lease，因此不必默认新增 cache-key 锁，但必须把单 writer 不变量纳入 perf(ios-simulator): 构建链路优化（arch 预检 + 缓存复用 + 回收） #2899 的测试门禁。
• feat(ios-simulator): 集成 Host 托管的内嵌 iOS Simulator #2044：已合并的 iOS Simulator Host 基础架构，建立了 ownership registry 和 profile 单 writer 模型；这是共享缓存跨进程安全的上层基础。
• fix(ios-simulator): release disabled Host and settle WDA fallback #2494：正在调整 capability 停用、Host 清理及 writer lease 释放时机，会直接影响共享缓存是否可能在旧 build 未结束时被新 Host 接管。

[BarneyZhaoooo]

已按方案 A 回应，实现在 PR #2899 的 fa1eaf0dd。

本 PR 采纳

1. lastUsed marker：cache key 在 build 准入和结束时写入 .cindy-last-used。prune 按这个时间判断 7 天未使用；顶层目录 mtime 旧、marker 新时不会删。无 marker 的旧目录才回退 mtime。
2. SPM fallback 收窄：只有 Xcode 明确报 Package.resolved 缺失/不可用时，才去掉 -onlyUsePackageVersionsFromResolvedFile 重试一次。普通编译失败日志里碰巧提到 Package.resolved 不重试。
3. 7 天 TTL 语义：这是机会式冷缓存回收，不是磁盘配额，不能保证总占用上限。容量/LRU 不进本 PR。

不进本 PR
2. 真机 Xcode/Simulator smoke：单测替代不了真实工程形态。这项作为本机验收证据补，不把 Darwin + 完整 Xcode 矩阵塞进本 fork PR 的 CI。
3. cache-key 跨进程锁：现有 profile writer lease 已经让第二进程在 initializeIOSSimulatorHost 时 DEVICE_BUSY，默认 Host 建不起来，碰不到共享 DerivedData/SPM。本 PR 不另加一把 key 级锁。#2919 仍独立，仅当未来允许同 profile 多 writer 时再做。

请维护者确认：接受「7 天机会式 TTL、暂无容量硬上限」，以及上述 2/3 不扩进 #2899。若要 Request Changes，请点名具体项。