cocoapods-podgenerate 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aba68b23582a229140c6580a31d506a3298d8389b6946f432e6429e1fbfe5edd
-  data.tar.gz: 2cd7a8c3bf26165fcc425f00bc03a9bffd566946d58cf126ff6c0ee6e47d97aa
+  metadata.gz: b6d26a277c924f83166f71d24a5c4268faac627ec35aa125b7771ba4f962d035
+  data.tar.gz: cf7d5a1740bcce3e2d9b55301ed07ae1a73a33083a1199e0027824eaf7c13e18
 SHA512:
-  metadata.gz: d631266d74333c37296f116a0bedb11e31989ab3a6307d531ed4c59a2a55f7f7e8e553294c87cab2eceaa22006ceda20efaa733c123566f6cdf2314b3176e42a
-  data.tar.gz: 402636b400e0db9a80b5240730063d23215ac5c58ed87c3ac044a52839eb5a4a5d15600e48a71bf1f6363de3aa85aeae6aff9c466f512f2aa49d6de9522f5621
+  metadata.gz: 2bf8fcda7f3bd691211959324e96bc61fa74172675ff1c93a518727513299104108689d844059e446510d07bc7b1a52a229032bd7c3e1483502df83ebe15e8ae
+  data.tar.gz: 50eae7e57d1883adf0dd706b1a67e31760670e088de0c2d45aeee22491243f44e6e00d8fd8ce592f1fe858e01c8d393bc69b62c98894e28b97efafea05a8683e

data/lib/cocoapods-podgenerate/benchmark/profiler.rb

@@ -9,15 +9,17 @@ module Pod
     module Benchmark
       module Profiler
         @phase_timings = []
+        @timings_mutex = Mutex.new
 
         class << self
           def enabled?
-            @enabled ||= ENV['POD_GENERATE_DEBUG'] == '1' ||
-                         ENV['COCOAPODS_PODGENERATE_DEBUG'] == '1'
+            ENV['POD_GENERATE_DEBUG'] == '1' ||
+              ENV['COCOAPODS_PODGENERATE_DEBUG'] == '1' ||
+              @enabled_override
           end
 
           def enable!
-            @enabled = true
+            @enabled_override = true
           end
 
           def install
@@ -27,7 +29,7 @@ module Pod
           end
 
           def record_phase(name, duration)
-            @phase_timings << [name, duration]
+            @timings_mutex.synchronize { @phase_timings << [name, duration] }
           end
 
           def report

data/lib/cocoapods-podgenerate/command.rb

@@ -1,5 +1,17 @@
 # frozen_string_literal: true
 
+# [cocoapods-podgenerate]
+# `pod podgenerate` CLI 命令 — 带优化运行 pod install 的快捷方式。
+#
+# 用法:
+#   pod podgenerate              # 运行优化的 pod install
+#   pod podgenerate --debug      # 启用详细性能分析输出
+#   pod podgenerate --verbose    # 传递 --verbose 给 pod install
+#
+# v0.1.4 修复 (M7):
+#   用户参数（如 --no-repo-update、--verbose）现在会正确传递给
+#   底层的 pod install 命令，不再被静默丢弃。
+
 module Pod
   class Command
     class Podgenerate < Command
@@ -20,19 +32,22 @@ module Pod
 
       def initialize(argv)
         @debug = argv.flag?('debug', false)
+        # v0.1.4: 保存原始参数，稍后传递给 pod install（修复 M7）
+        @remaining_argv = argv
         super
       end
 
       def run
-        Pod::PodGenerate.activate
-
         if @debug
+          Pod::PodGenerate::Benchmark::Profiler.enable!
           Pod::UI.puts '[cocoapods-podgenerate] Debug mode enabled — verbose profiling output will be shown.'
-          ENV['COCOAPODS_PODGENERATE_DEBUG'] = '1'
         end
 
-        # Delegate to the standard install command
-        install_command = Pod::Command::Install.new(CLAide::ARGV.new([]))
+        Pod::PodGenerate.activate
+
+        # 委托给标准的 pod install 命令执行
+        # v0.1.4: 传递用户原参数给 pod install（修复 M7）
+        install_command = Pod::Command::Install.new(CLAide::ARGV.new(@remaining_argv.remainder!))
         install_command.run
       end
     end

data/lib/cocoapods-podgenerate/parallel/batch_processor.rb

@@ -1,48 +1,49 @@
 # frozen_string_literal: true
 
 # [cocoapods-podgenerate]
-# Batch processor that splits work items across a thread pool.
-# Maintains ordering: results are returned in the same order as input items.
+# 批处理器 — 将工作项在线程池中并行分配处理。
+#
+# 用于将需要并行化的批量任务分配到 Concurrent::FixedThreadPool，
+# 保持结果的输入顺序（通过索引数组）。
+#
+# v0.1.4 改进：
+#   - wait_for_termination 添加超时（120s）防止死锁
+#   - 移除未使用的 batch_size 和 completed 变量
 
 require 'concurrent'
+require_relative 'thread_pool'
 
 module Pod
   module PodGenerate
     module Parallel
       module BatchProcessor
-        # Process items in batches using a thread pool.
-        # @param items [Array] list of items to process
-        # @param batch_size [Integer] max items per batch (nil = auto-size)
-        # @param pool [Concurrent::FixedThreadPool] the thread pool
-        # @yield [item] block to process each item
-        # @return [Array] results in same order as input items
-        def self.process(items, pool:, batch_size: nil, &block)
+        # 在线程池中并行处理项目，保持结果的输入顺序
+        #
+        # @param items [Array] 要处理的项目列表
+        # @param pool [Concurrent::FixedThreadPool] 线程池实例
+        # @yield [item] 处理每个项目的代码块
+        # @return [Array] 结果列表，顺序与输入相同（nil 表示处理失败的项目）
+        def self.process(items, pool:, &block)
           return [] if items.empty?
 
           results = Array.new(items.size)
           mutex = Mutex.new
-          count = items.size
-          completed = 0
 
           items.each_with_index do |item, idx|
             pool.post do
-              begin
-                result = block.call(item)
-                mutex.synchronize { results[idx] = result }
-              rescue StandardError => e
-                mutex.synchronize do
-                  Pod::UI.warn "[cocoapods-podgenerate] BatchProcessor error on item #{idx}: #{e.message}"
-                end
-              ensure
-                mutex.synchronize do
-                  completed += 1
-                end
-              end
+              result = block.call(item)
+              mutex.synchronize { results[idx] = result }
+            rescue StandardError => e
+              Pod::UI.warn "[cocoapods-podgenerate] BatchProcessor error on item #{idx}: #{e.message}"
             end
           end
 
-          # Wait for all tasks to complete
-          pool.wait_for_termination
+          # v0.1.4: 带超时的等待
+          pool.shutdown
+          unless pool.wait_for_termination(Pod::PodGenerate::Parallel::ThreadPool::DEFAULT_TIMEOUT)
+            Pod::UI.warn '[cocoapods-podgenerate] BatchProcessor timed out after 120s'
+            pool.kill
+          end
 
           results
         end

data/lib/cocoapods-podgenerate/parallel/thread_pool.rb

@@ -1,34 +1,25 @@
 # frozen_string_literal: true
 
 # [cocoapods-podgenerate]
-# Thread pool wrapper using plain Ruby Thread.
-# Provides CPU-core-aware pool sizing with work queue and error handling.
+# 线程池工具模块 — 提供跨所有补丁共享的线程池大小计算和超时配置。
+
+require 'etc'
 
 module Pod
   module PodGenerate
     module Parallel
       module ThreadPool
+        # 默认的线程池等待超时（秒）
+        DEFAULT_TIMEOUT = 120
+
         class << self
-          def default_size
-            @default_size ||= [Etc.nprocessors - 1, 2].max
+          # 计算适合当前机器的线程池大小
+          # 使用 nproc - 1（为主线程留一个核心），最小 2，最大 16
+          # @return [Integer] 推荐的线程池大小
+          def pool_size
+            [[Etc.nprocessors - 1, 2].max, 16].min
           rescue NameError
-            @default_size ||= 4
-          end
-
-          # Create and yield a thread pool, then shut it down.
-          def with_pool(size: nil, &block)
-            pool = create(size: size)
-            yield pool
-          ensure
-            pool&.each(&:kill)
-          end
-
-          def create(size: nil)
-            pool_size = size || default_size
-            # Return an array of available threads - caller manages them
-            Array.new(pool_size) { Thread.new { sleep } }.each(&:exit)
-            # We use a simpler approach - caller creates threads directly
-            nil
+            4
           end
         end
       end

data/lib/cocoapods-podgenerate/patches/analyzer_patch.rb

@@ -1,16 +1,40 @@
 # frozen_string_literal: true
 
 # [cocoapods-podgenerate]
-# Monkey-patches Analyzer to cache dependency resolution results.
+# Monkey-patches Analyzer 来缓存依赖解析结果，跳过 Molinillo 算法。
 #
-# Molinillo resolution is O(pods^2) worst case and takes 30-120s for 200+ pods.
-# For the common case where Podfile and podspecs haven't changed, we can skip
-# resolution entirely and use cached results from a previous run.
+# Molinillo 依赖解析的时间复杂度在最坏情况下为 O(n²)（n = pod 数量），
+# 对于 200+ pod 的项目需要 30-120 秒。
 #
-# Cache key: SHA256 of (Podfile content + all podspec checksums + locked deps)
-# Cache stored in: Pods/.cocoapods-resolution-cache.yaml
+# 优化策略：
+#   - 首次运行后，保存解析结果（按 TargetDefinition 分组的 pod 名→版本号映射）
+#     到缓存文件
+#   - 缓存键 = SHA256(Podfile.to_yaml + Podfile.lock.to_yaml + CocoaPods 版本号)
+#   - 后续运行时，如果缓存命中，从 Manifest 的 specifications 重建完整 Specification
+#     对象列表，完全跳过 Molinillo 解析
 #
-# Reference: CocoaPods source — lib/cocoapods/installer/analyzer.rb
+# YAML 序列化可行性说明：
+#   - Specification 对象包含大量内部状态（Source、Checksum、Platform 等），
+#     无法直接 YAML 序列化（会触发 Marshal.dump 或递归深度错误）
+#   - 解决方案：只保存 pod_name（字符串）和 version（字符串），它们是 Ruby
+#     基本类型，可以安全地序列化为 YAML
+#   - 下次加载时，通过 sandbox.manifest.specifications 获取所有已安装的完整
+#     Specification 对象，按名称匹配重建结果 Hash
+#   - sandbox.manifest 是 Podfile.lock 的内存表示，在 pod install 开始时即加载，
+#     反映上一次成功安装的状态。当 Podfile 和 lockfile 都未改变时，
+#     manifest 中的 specification 与 Molinillo 将解析出的结果完全一致
+#
+# 线程安全：
+#   - 所有操作在主线程中执行（Analyzer#resolve_dependencies 在 install! 主流程中）
+#   - 文件 I/O 使用原子写入（临时文件 + rename）避免写入中断导致缓存损坏
+#
+# 缓存失效条件（任一满足即视为 MISS，触发完整 Molinillo 解析）：
+#   - Podfile 内容发生任何变化
+#   - Podfile.lock 内容发生任何变化
+#   - CocoaPods 版本升级
+#   - 缓存文件不存在或格式损坏
+#
+# 参考：CocoaPods 源码 — lib/cocoapods/installer/analyzer.rb
 
 require 'digest'
 require 'yaml'
@@ -19,90 +43,240 @@ module Pod
   module PodGenerate
     module Patches
       module AnalyzerPatch
+        # 缓存文件路径（相对于 Pods 目录）
+        # 放在 Pods 目录下，与其他生成物一起管理
         CACHE_FILE = '.cocoapods-resolution-cache.yaml'
 
+        # 应用补丁入口
+        # 将 CachedResolution 模块 prepend 到 Pod::Installer::Analyzer，
+        # 使得 resolve_dependencies 方法先执行缓存逻辑
         def self.apply
           Pod::UI.message '[cocoapods-podgenerate] Applying AnalyzerPatch (resolution cache)'
           Pod::Installer::Analyzer.prepend(CachedResolution)
         end
 
+        # 缓存解析结果的模块
+        # 通过 prepend 机制覆盖 Analyzer#resolve_dependencies，
+        # 在 Molinillo 执行前后插入缓存读写逻辑
         module CachedResolution
-          # Override resolve_dependencies to check cache first
-          # Must accept the locked_dependencies parameter from the original method
+          # 重写 resolve_dependencies，利用缓存跳过 Molinillo 解析
+          #
+          # 工作流程：
+          #   1. compute_resolution_cache_key: 计算当前 Podfile + lockfile 的 SHA256 缓存键
+          #   2. load_cached_result: 如果缓存命中且有效，从 Manifest 重建 specs_by_target 并返回
+          #   3. super(locked_dependencies): 缓存未命中，调用原始 Molinillo 解析
+          #   4. save_cached_result: 保存本次解析结果到 YAML 文件供下次使用
+          #
+          # @param locked_dependencies [Hash] 锁定的依赖关系，传递给原始解析器
+          # @return [Hash{TargetDefinition => Array<Specification>}]
+          #   每个 Podfile TargetDefinition 映射到其依赖的 Specification 对象数组
           def resolve_dependencies(locked_dependencies)
+            # 步骤 1：计算缓存键（SHA256，基于 Podfile + lockfile 内容）
             cache_key = compute_resolution_cache_key(locked_dependencies)
-            cached = load_cached_result(cache_key)
 
+            # 步骤 2：尝试从缓存加载并重建结果
+            cached = load_cached_result(cache_key)
             if cached
-              Pod::UI.message '[cocoapods-podgenerate] Resolution cache HIT — skipping Molinillo resolution'
+              Pod::UI.message '[cocoapods-podgenerate] 解析缓存命中 - 跳过 Molinillo 解析'
               return cached
             end
 
-            Pod::UI.message '[cocoapods-podgenerate] Resolution cache MISS — resolving dependencies'
+            # 步骤 3：缓存未命中，执行完整的 Molinillo 依赖解析
+            Pod::UI.message '[cocoapods-podgenerate] 解析缓存未命中 - 运行 Molinillo 解析'
             result = super(locked_dependencies)
 
+            # 步骤 4：保存解析结果到缓存（只保存可序列化的名称和版本）
             save_cached_result(cache_key, result)
             result
           end
 
           private
 
+          # 计算缓存键：SHA256(Podfile.to_yaml + Manifest.to_yaml + CocoaPods 版本)
+          #
+          # 为什么使用 to_yaml 而不是 to_s/to_hash：
+          #   - to_s 返回的对象字符串表示可能包含内存地址（如 #<Podfile:0x00007f...>），
+          #     在跨进程中不稳定，导致缓存永久失效
+          #   - to_yaml 产出纯文本的、确定性的 YAML 序列化结果，
+          #     只要 Podfile 语义不变，YAML 输出就不变
+          #
+          # 加入 CocoaPods 版本号的原因：
+          #   - 不同版本的 CocoaPods 可能有不同的解析行为（API 变更、bug 修复）
+          #   - 版本升级时自动使所有缓存失效，确保使用新版本的解析逻辑
+          #
+          # @param locked_deps [Hash] 锁定的依赖关系，序列化后加入键中
+          # @return [String] 64 位十六进制 SHA256 摘要字符串
           def compute_resolution_cache_key(locked_deps)
-            # Hash the Podfile content
-            pf_content = podfile.to_hash.to_s if respond_to?(:podfile) && podfile
+            # Podfile 内容：使用 to_yaml 获得稳定的确定性序列化
+            pf_content = ''
+            if respond_to?(:podfile) && podfile
+              pf_content = podfile.to_yaml
+            end
 
-            # Include checksums from lockfile if available
-            checksum_data = ''
+            # Podfile.lock 内容（通过 sandbox.manifest 访问）
+            # 也使用 to_yaml 确保序列化稳定性
+            lockfile_content = ''
             if sandbox && sandbox.manifest
-              checksum_data = sandbox.manifest.to_hash.to_s
+              lockfile_content = sandbox.manifest.to_yaml
             end
 
-            locked_deps_str = locked_deps.to_s if locked_deps
+            # 锁定的依赖关系，使用 YAML 序列化
+            locked_deps_str = locked_deps.to_yaml if locked_deps
 
-            raw = [pf_content, checksum_data, locked_deps_str, Pod::VERSION].join('|')
+            # 组合所有输入并计算 SHA256 哈希
+            # 使用 '|' 作为分隔符避免不同输入的意外拼接
+            raw = [pf_content, lockfile_content, locked_deps_str, Pod::VERSION].join('|')
             Digest::SHA256.hexdigest(raw)
           end
 
+          # 返回缓存文件的完整绝对路径
+          #
+          # @return [String] 缓存文件的绝对路径（位于 Pods 目录下）
           def cache_path
             sandbox_root = sandbox.root
-            cache_dir = sandbox_root.to_s
-            File.join(cache_dir, CACHE_FILE)
+            File.join(sandbox_root.to_s, CACHE_FILE)
           end
 
+          # 从 YAML 缓存文件加载并重建解析结果
+          #
+          # 缓存文件 YAML 格式：
+          #   cache_key: <SHA256 字符串>
+          #   timestamp: <时间戳，供调试参考>
+          #   cocoaPods_version: <CocoaPods 版本号>
+          #   pod_count: <总 pod 数量，供调试参考>
+          #   targets:
+          #     Pods-MyApp:           # TargetDefinition 的名称
+          #       - pod_name: A       # pod 的根名称
+          #         version: 1.0.0    # pod 的版本号字符串
+          #     Pods-MyApp-Tests:
+          #       - pod_name: B
+          #         version: 2.0.0
+          #
+          # 重建策略（关键实现细节）：
+          #   1. 从 sandbox.manifest.specifications 获取所有已安装的 Specification 对象
+          #      （Manifest = Podfile.lock 的内存表示，在 pod install 开始时已加载）
+          #   2. 按 pod 名称分组建立索引
+          #   3. 从 podfile.target_definitions 获取 TargetDefinition 对象
+          #   4. 按缓存中记录的目标→pod 关系，组装 Hash{TargetDefinition => [Spec]}
+          #
+          # 为什么 Manifest 中的 specs 就是正确的：
+          #   缓存命中意味着 Podfile 和 Podfile.lock 都未改变，
+          #   而 Manifest 反映的是上一次 pod install 成功的状态，
+          #   此时 Manifest 中的 specifications 与 Molinillo 将解析出的结果一致
+          #
+          # @param cache_key [String] 期望的缓存键，与文件中存储的键比较验证有效性
+          # @return [Hash, nil] 重建的解析结果（TargetDefinition => [Specification]），
+          #   如果缓存无效、过期或损坏则返回 nil
           def load_cached_result(cache_key)
             path = cache_path
             return nil unless File.exist?(path)
 
+            # 安全地加载 YAML，允许 Symbol 类型的反序列化
             data = YAML.safe_load(File.read(path), permitted_classes: [Symbol])
             return nil unless data.is_a?(Hash)
+
+            # 验证缓存键匹配 — 如果不匹配说明 Podfile 或 lockfile 已变化
             return nil unless data['cache_key'] == cache_key
 
-            # We can't easily serialize and deserialize the full resolver result,
-            # but we can signal the caller to skip resolution.
-            # The cache stores the key + metadata to verify validity.
-            # On cache hit, we return the wrapped result.
-            data['result']
+            cached_targets = data['targets']
+            return nil unless cached_targets.is_a?(Hash) && !cached_targets.empty?
+
+            # 步骤 1：从 Manifest 获取所有已安装的 Specification 对象
+            # manifest.specifications 返回 Array<Specification>
+            manifest_specs = sandbox.manifest.specifications
+
+            # 步骤 2：按 pod 根名称建立索引
+            # 注意：一个 pod 可能有多个 subspec，它们共享同一个 root.name
+            # 使用 group_by 将同名 pod 的所有 spec（含 subspec）归为一组
+            specs_by_name = {}
+            manifest_specs.each do |spec|
+              name = spec.root.name
+              specs_by_name[name] ||= []
+              specs_by_name[name] << spec
+            end
+
+            # 步骤 3：从 Podfile 获取 TargetDefinition 对象，按名称建立索引
+            # podfile.target_definitions 包含所有抽象 target 和具体 target
+            target_defs_by_name = {}
+            podfile.target_definitions.each do |td|
+              target_defs_by_name[td.name] = td
+            end
+
+            # 步骤 4：按缓存记录的目标→pod 关系，重建 {TargetDefinition => [Spec]}
+            result = {}
+            cached_targets.each do |target_name, pods_data|
+              target_def = target_defs_by_name[target_name]
+              next unless target_def  # 跳过缓存中存在但 Podfile 中已删除的目标
+
+              specs = []
+              pods_data.each do |pod_entry|
+                pod_name = pod_entry['pod_name']
+                pod_specs = specs_by_name[pod_name]
+                specs.concat(pod_specs) if pod_specs
+              end
+              result[target_def] = specs unless specs.empty?
+            end
+
+            return nil if result.empty?
+            result
           rescue StandardError => e
-            Pod::UI.warn "[cocoapods-podgenerate] Failed to load resolution cache: #{e.message}"
+            # 缓存加载失败不应中断 pod install 主流程
+            # 最坏情况：缓存文件损坏 → MISS → 正常 Molinillo 解析
+            Pod::UI.warn "[cocoapods-podgenerate] 加载解析缓存失败: #{e.message}"
             nil
           end
 
+          # 将 Molinillo 解析结果保存到 YAML 缓存文件
+          #
+          # 保存策略：
+          #   - 不保存 Specification 对象（无法序列化）
+          #   - 只保存 pod 名称+版本号字符串
+          #   - 按 TargetDefinition 名称组织数据结构
+          #   - 使用原子写入（临时文件 + rename）避免写入中断导致缓存损坏
+          #
+          # 原子写入步骤：
+          #   1. 先写入 .tmp 临时文件
+          #   2. 写入完成后 rename 到目标文件
+          #   3. rename 是原子操作，避免了进程崩溃时残留损坏的缓存文件
+          #
+          # @param cache_key [String] 缓存键，写入文件头部供下次 load 验证
+          # @param result [Hash{TargetDefinition => Array<Specification>}] Molinillo 解析结果
           def save_cached_result(cache_key, result)
             path = cache_path
+
+            # 提取纯数据：从 Specification 对象中只取名称和版本号
+            # Specification.root.name 返回 pod 的根名称（不含 subspec 后缀）
+            # Specification.version.to_s 返回版本号字符串（如 "1.2.3"）
+            targets_data = {}
+            result.each do |target_def, specs|
+              pod_list = specs.map do |spec|
+                {
+                  'pod_name' => spec.root.name,
+                  'version' => spec.version.to_s,
+                }
+              end
+              # 去重：同一个 pod 的多个 subspec 共享相同的 root.name
+              pod_list.uniq! { |entry| entry['pod_name'] }
+              targets_data[target_def.name] = pod_list unless pod_list.empty?
+            end
+
+            # 组装缓存数据
             data = {
               'cache_key' => cache_key,
               'timestamp' => Time.now.to_s,
-              'pod_count' => result.is_a?(Hash) ? result.keys.size : result.to_s.size,
+              'cocoaPods_version' => Pod::VERSION,
+              'pod_count' => targets_data.values.flatten.size,
+              'targets' => targets_data,
             }
-            # Note: full resolver result serialization is complex.
-            # For now, the cache key serves as invalidation mechanism.
-            # In a production implementation, we'd serialize the specification
-            # graph, but the key insight is that cocoapods-core already caches
-            # specs in the sandbox. This cache avoids the Molinillo algorithm
-            # re-run when nothing changed.
-            File.write(path, YAML.dump(data))
+
+            # 原子写入：先写临时文件，成功后再 rename
+            tmp_path = "#{path}.tmp"
+            File.write(tmp_path, YAML.dump(data))
+            File.rename(tmp_path, path)
           rescue StandardError => e
-            Pod::UI.warn "[cocoapods-podgenerate] Failed to save resolution cache: #{e.message}"
+            # 缓存保存失败不应中断 pod install 主流程
+            # 最坏情况：下次运行时缓存 MISS → 正常 Molinillo 解析
+            Pod::UI.warn "[cocoapods-podgenerate] 保存解析缓存失败: #{e.message}"
           end
         end
       end

data/lib/cocoapods-podgenerate/patches/cache_analyzer_patch.rb

@@ -1,16 +1,35 @@
 # frozen_string_literal: true
 
 # [cocoapods-podgenerate]
-# Monkey-patches ProjectCacheAnalyzer to parallelize cache key computation.
+# Monkey-patches ProjectCacheAnalyzer，并行计算缓存键。
 #
-# v0.1.2 Optimization:
-#  1. Parallel MD5 cache key computation across all pod targets
+# 优化原理：
+#   ProjectCacheAnalyzer#create_cache_key_mappings 为所有 pod_target
+#   和 aggregate_target 计算 TargetCacheKey。每个 target 的计算需要
+#   - 遍历文件列表计算 MD5 校验和
+#   - 汇总上游依赖的资源信息
+#   所有 target 的计算完全独立，天然适合并行化。
 #
-# TargetCacheKey.from_pod_target computes MD5 checksums of build settings
-# and collects resource dependencies per target. Each computation is fully
-# independent and can run in parallel.
+# 性能收益（150 pod target 场景）：
+#   原串行实现逐个计算 MD5，总耗时随 pod 数量线性增长。
+#   线程池并行后，计算时间除以线程数（通常 10+ 线程 → ~10x 加速）。
 #
-# Reference: CocoaPods — lib/cocoapods/installer/project_cache/project_cache_analyzer.rb
+# v0.1.3 修复：
+#   - Bug 修复：线程内错误不再导致 nil 条目。异常时同步重试，
+#     确保 results Hash 中每个 label 都有有效的 TargetCacheKey。
+#
+# v0.1.4 改进：
+#   - M1: wait_for_termination 添加 120 秒超时
+#   - 优化 compute_cache_key 为独立方法便于错误恢复
+#   - 添加详细中文注释
+#
+# 线程安全保证：
+#   - sandbox.local? 和 sandbox.checkout_sources 都是只读操作
+#   - target_by_label Hash 在所有线程间只读共享
+#   - results Hash 的写入用 Mutex 保护
+#
+# 参考：CocoaPods 源码
+#   - lib/cocoapods/installer/project_cache/project_cache_analyzer.rb
 
 require 'concurrent'
 require 'etc'
@@ -25,9 +44,19 @@ module Pod
         end
 
         module ParallelCacheKeyComputation
-          # Override create_cache_key_mappings to parallelize MD5 computation
-          # The original iterates target_by_label sequentially, computing cache keys.
-          # Since each target is independent, we use a thread pool.
+          # 并行计算所有 target 的缓存键
+          #
+          # 原实现（串行）:
+          #   Hash[target_by_label.map { |label, target| [label, compute_key(target)] }]
+          #
+          # 优化后（并行）:
+          #   使用 Concurrent::FixedThreadPool，每个 target 分配一个线程，
+          #   并发计算 TargetCacheKey，结果通过 Mutex 合并到 results Hash。
+          #
+          # @param target_by_label [Hash{String => PodTarget|AggregateTarget}]
+          #   target 标签到 target 对象的映射
+          # @return [Hash{String => TargetCacheKey}]
+          #   target 标签到缓存键的映射
           def create_cache_key_mappings(target_by_label)
             UI.message '- Creating cache key mappings (parallel)' do
               pool_size = compute_pool_size
@@ -35,27 +64,42 @@ module Pod
               mutex = Mutex.new
               results = {}
 
+              # 为每个 target 提交一个线程任务
               target_by_label.each do |label, target|
                 pool.post do
                   key = compute_cache_key(target, target_by_label)
                   mutex.synchronize { results[label] = key }
                 rescue StandardError => e
-                  # Bug fix v0.1.3: compute fallback key synchronously to avoid nil
-                  # entries that would crash ProjectCacheAnalyzer#analyze downstream
+                  # v0.1.3 bug 修复: 异常时同步重试，确保 results[label] 不为 nil
+                  # 如果重试仍然失败，异常会传播导致 pod install 失败（正确的行为）
                   Pod::UI.warn "[cocoapods-podgenerate] Cache key computation error, retrying sync: #{e.message}"
                   fallback_key = compute_cache_key(target, target_by_label)
                   mutex.synchronize { results[label] = fallback_key }
                 end
               end
 
+              # v0.1.4: 带超时的等待
               pool.shutdown
-              pool.wait_for_termination
+              unless pool.wait_for_termination(Pod::PodGenerate::Parallel::ThreadPool::DEFAULT_TIMEOUT)
+                Pod::UI.warn '[cocoapods-podgenerate] Cache key computation timed out after 120s'
+                pool.kill
+              end
+
               results
             end
           end
 
           private
 
+          # 计算单个 target 的缓存键
+          #
+          # 根据 target 类型（PodTarget 或 AggregateTarget）调用不同的计算逻辑:
+          #   - PodTarget:  检查是否本地 pod + checkout 选项 → from_pod_target
+          #   - AggregateTarget: 直接调用 from_aggregate_target
+          #
+          # @param target [PodTarget|AggregateTarget] 要计算的目标
+          # @param target_by_label [Hash] 完整的 label→target 映射（from_pod_target 需要）
+          # @return [TargetCacheKey] 缓存键对象
           def compute_cache_key(target, target_by_label)
             case target
             when PodTarget
@@ -71,6 +115,7 @@ module Pod
             end
           end
 
+          # 计算线程池大小
           def compute_pool_size
             [[Etc.nprocessors - 1, 2].max, 16].min
           rescue NameError