cocoapods-yaml 1.0.0

data/lib/core/logger.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'colored2'
+
+module CocoaPods
+  module Yaml
+    # 统一日志，替代散落各处的 puts/warn。
+    #
+    # 级别:
+    #   step    阶段标题(⏩，前置空行)
+    #   info    普通信息(默认色)
+    #   detail  细节说明/阶段性完成(-> 前缀)；流程内各步骤完成统一用此级别
+    #   success 成功提示(✅，绿色)；仅用于整条命令/流程的最终关键结果，阶段步骤不要用，避免满屏✅
+    #   warn    警告(⚠️，黄色，不中断流程)
+    #   error   错误(❌，红色；是否退出由调用方决定)
+    #   debug   调试细节(· 前缀，仅 pod install --verbose 或 COCOAPODS_YAML_VERBOSE 非空时输出)
+    #
+    # 说明: warn/error也输出到stdout而非stderr。本插件运行在CocoaPods进程内，
+    # 分流到stderr会被CocoaPods自身输出缓冲穿插，导致警告标题与其明细行错位。
+    # 仅当输出流是TTY时才着色，避免CI/重定向日志中出现ANSI转义码。
+    class Logger
+      DEBUG_ENV = 'COCOAPODS_YAML_VERBOSE'
+
+      def step(message)
+        write($stdout, "\n⏩ #{message}", :cyan, true)
+      end
+
+      def info(message = '', color = nil)
+        write($stdout, message.to_s, color)
+      end
+
+      def detail(message)
+        write($stdout, "-> #{message}", :blue)
+      end
+
+      def success(message)
+        write($stdout, "✅ #{message}", :green)
+      end
+
+      def warn(message)
+        write($stdout, "⚠️ #{message}", :yellow)
+      end
+
+      def error(message)
+        write($stdout, "❌ #{message}", :red)
+      end
+
+      def debug(message)
+        write($stdout, "· #{message}", nil) if debug_enabled?
+      end
+
+      def debug_enabled?
+        return true unless ENV.fetch(DEBUG_ENV, '').strip.empty?
+        if defined?(Pod::Config)
+          begin
+            return !!Pod::Config.instance.verbose?
+          rescue StandardError
+            false
+          end
+        end
+        false
+      end
+
+      private
+
+      # @param io [IO] 输出流
+      # @param message [String] 内容
+      # @param color [Symbol, nil] 颜色方法(colored2)，nil不着色
+      # @param bold [Boolean] 是否加粗
+      def write(io, message, color, bold = false)
+        text = message
+        if color && io.respond_to?(:tty?) && io.tty?
+          text = text.public_send(color)
+          text = text.bold if bold
+        end
+        io.puts(text)
+      end
+    end
+
+    # @return [CocoaPods::Yaml::Logger] 全局日志实例
+    def self.log
+      @log ||= Logger.new
+    end
+  end
+end

data/lib/core/modify/source_patcher.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'find'
+require 'pathname'
+
+module ModifyCode
+  # 三方库源码编译兼容补丁
+  #
+  # 在 pod install/update 的 post_install 阶段，对集成进工程的三方库源码做
+  # 不改变功能的微调，使其能在新版 Xcode 上编译。放在 cocoapods-yaml 中执行是为了
+  # 同时覆盖两种使用场景，避免“打包机能编译、开发者源码接入却编译失败”：
+  #   1. 日常开发的普通 pod 源码接入(Pods/<组件名>)
+  #   2. pod-binary-pack 打包期的 :path 开发 pod(源码目录可能在 Pods 之外)
+  # 二进制 pod 目录下仅含 .framework/.xcframework，遍历源码时会剪枝跳过，绝不改动已构建产物
+  class SourcePatcher
+    # 可编译源码后缀
+    SOURCE_SUFFIX = %w[.h .m .mm .c .cpp].freeze
+    # 设置该环境变量可临时关闭全部源码兼容补丁
+    DISABLE_ENV = 'COCOAPODS_YAML_SKIP_SOURCE_PATCH'
+
+    # 一条兼容规则
+    #   pod:       组件名；nil 表示对所有组件的源码生效(规则本身必须安全通用)
+    #   files:     相对组件源码根的精确文件路径数组；nil 表示遍历全部源码文件
+    #   pattern:   String 时字面匹配，Regexp 时可用 \1 \2 反向引用
+    #   replacement 配合 pattern 使用，日志标签 label 便于定位是哪条兼容规则
+    Rule = Struct.new(:pod, :files, :pattern, :replacement, :label, keyword_init: true) do
+      def global?
+        pod.nil?
+      end
+    end
+
+    # 规则按声明顺序执行；新增同类兼容处理时在此追加一条即可，不要把逻辑散落各处
+    RULES = [
+      # 通用规则：新版 Xcode(16+) SDK 将 netinet6/in6.h 划为 Darwin 模块私有头，
+      # 且该头内部 #error 明确要求改引公共头 netinet/in.h(AFNetworking 4.0.1 等旧库因此编译失败)
+      Rule.new(
+        pod: nil,
+        files: nil,
+        pattern: /^(\s*#\s*(?:import|include)\s*[<"])netinet6\/in6\.h([>"])/,
+        replacement: '\\1netinet/in.h\\2',
+        label: 'netinet6/in6.h 已废弃，改用公共头 netinet/in.h'
+      ),
+
+      # YYText 1.0.7：命中字符簇/emoji 内部时按距离远近吸附到左右边界，
+      # 原代码把三元运算符误写成链式比较 a < b < c，Xcode 16+ 将 -Wparentheses 升级为编译错误。
+      # 同文件内垂直/水平两种写法各出现 2 次，String 精确替换全部命中
+      Rule.new(
+        pod: 'YYText',
+        files: ['YYText/Component/YYTextLayout.m'],
+        pattern: 'position = fabs(left - point.y) < fabs(right - point.y) < (right ? prev : next);',
+        replacement: 'position = fabs(left - point.y) < fabs(right - point.y) ? prev : next;',
+        label: '修复链式比较 X<Y<Z 为最近边界三元选择'
+      ),
+      Rule.new(
+        pod: 'YYText',
+        files: ['YYText/Component/YYTextLayout.m'],
+        pattern: 'position = fabs(left - point.x) < fabs(right - point.x) < (right ? prev : next);',
+        replacement: 'position = fabs(left - point.x) < fabs(right - point.x) ? prev : next;',
+        label: '修复链式比较 X<Y<Z 为最近边界三元选择'
+      ),
+
+      # FBRetainCycleDetector 历史编译兼容(原 modify_fb 逻辑原样迁移为规则)
+      Rule.new(
+        pod: 'FBRetainCycleDetector',
+        files: ['FBRetainCycleDetector/Layout/Classes/FBClassStrongLayout.mm'],
+        pattern: 'layoutCache[currentClass] = ivars;',
+        replacement: 'layoutCache[(id<NSCopying>)currentClass] = ivars;',
+        label: '修复新版 Xcode 下 layoutCache 下标类型不匹配'
+      ),
+      Rule.new(
+        pod: 'FBRetainCycleDetector',
+        files: ['fishhook/fishhook.c'],
+        pattern: 'indirect_symbol_bindings[i] = cur->rebindings[j].replacement;',
+        replacement: 'if(i < (sizeof(indirect_symbol_bindings) /sizeof(indirect_symbol_bindings[0]))) {indirect_symbol_bindings[i]=cur->rebindings[j].replacement;}',
+        label: '修复 fishhook 数组越界风险'
+      ),
+      Rule.new(
+        pod: 'FBRetainCycleDetector',
+        files: ['FBRetainCycleDetector/Graph/FBObjectiveCGraphElement.mm'],
+        pattern: '#import <objc/runtime.h>',
+        replacement: "#import  <objc/runtime.h>\n#import <malloc/malloc.h>",
+        label: '补充 malloc/malloc.h 头引用'
+      ),
+      Rule.new(
+        pod: 'FBRetainCycleDetector',
+        files: ['FBRetainCycleDetector/Graph/FBObjectiveCGraphElement.mm'],
+        pattern: 'Class aCls = object_getClass(object);',
+        replacement: 'malloc_zone_t *zone = malloc_zone_from_ptr((__bridge void *)object); if (zone) { Class aCls=object_getClass(object);',
+        label: 'malloc_zone 增加非空保护'
+      ),
+      Rule.new(
+        pod: 'FBRetainCycleDetector',
+        files: ['FBRetainCycleDetector/Graph/FBObjectiveCGraphElement.mm'],
+        pattern: '#endif',
+        replacement: "}\n# endif",
+        label: '补齐 malloc_zone 非空保护的闭合括号'
+      )
+    ].freeze
+
+    # post_install 钩子入口
+    # @param sandbox [Pod::Sandbox] post_install 上下文中的沙盒
+    def self.patch(sandbox)
+      return if ENV.key?(DISABLE_ENV)
+      return unless sandbox
+
+      new(sandbox).patch
+    end
+
+    def initialize(sandbox)
+      @sandbox = sandbox
+    end
+
+    def patch
+      roots = pod_source_roots
+      return if roots.empty?
+
+      RULES.each do |rule|
+        targets = rule.global? ? roots : roots.select { |name, _| name == rule.pod }
+        targets.each do |pod_name, root|
+          hit_files = apply_rule(rule, pod_name, root)
+          # 兼容补丁可能改变三方库原始行为，实际命中的文件逐条用警告级别记录，
+          # 确保默认日志可见、有迹可查；无改动则完全静默
+          hit_files.each do |relative|
+            CocoaPods::Yaml.log.warn("源码兼容补丁[#{rule.label}]：#{pod_name}/#{relative}")
+          end
+        end
+      end
+    end
+
+    private
+
+    # 收集本次安装实际存在源码的组件根目录：开发 pod(:path) + 普通 pod(Pods/<名>)
+    # @return [Hash{String => String}] 组件名 => 源码根绝对路径
+    def pod_source_roots
+      roots = {}
+
+      # 组件名取 Manifest.lock 实际安装列表 + 开发 pod(:path)列表(后者兜底 Manifest 缺失场景)。
+      # 注意：development_pods 存的是 podspec 文件路径(如 /path/YYText.podspec.json)而非源码目录，
+      # 不能直接遍历它；统一走 sandbox.pod_dir —— 开发 pod 内部取 dirname、普通 pod 取 Pods/<名>
+      names = []
+      manifest = @sandbox.respond_to?(:manifest) ? @sandbox.manifest : nil
+      names.concat(manifest.pod_names) if manifest
+      names.concat(@sandbox.development_pods.keys)
+      names.uniq.each do |name|
+        dir = @sandbox.pod_dir(name)
+        roots[name] = dir.to_s if dir&.directory?
+      end
+
+      roots
+    end
+
+    # @return [Array<String>] 实际被改动文件的相对路径
+    def apply_rule(rule, pod_name, root)
+      files =
+        if rule.files
+          rule.files.map { |rel| File.join(root, rel) }.select { |f| File.file?(f) }
+        else
+          source_files(root)
+        end
+
+      files.filter_map do |file|
+        relative = file.sub("#{root}/", '')
+        relative if replace_in_file(file, rule)
+      end
+    end
+
+    # 遍历组件根下全部源码文件，剪枝 .git 与 .framework/.xcframework 等产物目录
+    def source_files(root)
+      result = []
+      Find.find(root) do |path|
+        base = File.basename(path)
+        if File.directory?(path)
+          # .framework/.xcframework 是目录名后缀(如 BinKit.framework)，.git 为精确目录名
+          Find.prune if base == '.git' || base.end_with?('.framework', '.xcframework')
+        elsif File.file?(path) && SOURCE_SUFFIX.include?(File.extname(path).downcase)
+          result << path
+        end
+      end
+      result
+    rescue Errno::ENOENT
+      []
+    end
+
+    # @return [Boolean] 文件是否实际发生了改动
+    def replace_in_file(file, rule)
+      # 二进制方式读写：源码文件不一定是 UTF-8，按字节处理避免转码崩溃
+      content = File.binread(file)
+      updated =
+        if rule.pattern.is_a?(Regexp)
+          content.gsub(rule.pattern, rule.replacement)
+        else
+          # String 模式：替换内容原样使用，避免反斜杠被当成反向引用
+          content.gsub(rule.pattern) { rule.replacement }
+        end
+      return false if updated == content
+
+      # 三方库源码文件可能只读(历史上有此情况)，先确保可写
+      FileUtils.chmod('u+w', file)
+      File.binwrite(file, updated)
+      true
+    end
+  end
+end

data/lib/core/my_constants.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+module MyConstants
+
+  # 本地依赖覆盖文件(全局唯一，不提交git)
+  LOCAL_DEPENDENCIES_YAML = 'LocalDependencies.yaml'
+  # 每个target的依赖文件后缀: <TargetName>Dependencies.yaml
+  DEPENDENCIES_YAML_SUFFIX = 'Dependencies.yaml'
+  # 打包进bundle的依赖清单后缀(仅Debug): <TargetName>Dependencies.json
+  DEPENDENCIES_JSON_SUFFIX = 'Dependencies.json'
+  PODFILE_LOCK = 'Podfile.lock'
+  PODFILE = 'Podfile'
+
+  LIBLIBARYS = %w[time removefile AppleTextureEncoder standards AvailabilityMacros semaphore SystemHealthClient dns_sd ftw checkint pwd bitstring utime err CommonCrypto inttypes resolv c++ _ctermid stdlib sysdir unwind fts vis AvailabilityVersions membership libxml2 ulimit _stdio ntsid net notify_keys CMakeLists.txt AssertMacros float aio libxml ConditionalMacros locale fmtmsg unicode _wctype cpio langinfo xlocale limits Endian unwind_itanium _types db bank _ctype unistd stddef dispatch wctype fcntl mach_debug Availability stringlist tar readpassphrase _locale ttyent bzlib cache signal dirent mpool libDER unwind_arm_ehabi spawn crt_externs simd regex AvailabilityInternal arpa syslog bsm netinet libunwind libgen corpses rpcsvc monetary compression expat_external setjmp tgmath notify getopt _regex dlfcn strings TargetConditionals fnmatch pthread xlocale execinfo networkext printf architecture alloca sys iconv fenv expat grp secure ctype fstab pthread_spis machine SystemHealthManager voucher wordexp zlib nl_types paths AppleEXR wchar sqlite3 util gethostuuid sched sqlite3ext iso646 Block netdb pthread math memory asl __wctype mach errno device termios copyfile os xattr_flags poll _xlocale stdio mach-o malloc string_x86 arm Spatial __libunwind_config nameser dns _types rpc netinet6 pthread_impl objc MacTypes libkern uuid search assert AppleArchive cache_callbacks dns_util glob ifaddrs utmpx sandbox arm64 stdint complex runetype zconf ucontext sysexits string ndbm]
+  FRAMEWORKS = %w[MetricKit Network GameKit AddressBookUI CreateML Speech SafariServices ProximityReader Metal AppClip QuartzCore CoreGraphics StoreKit GSS CoreML WatchConnectivity UserNotificationsUI ARKit CoreLocationUI MetalPerformanceShaders AutomaticAssessmentConfiguration ExternalAccessory MediaPlayer LinkPresentation IdentityLookupUI MediaToolbox UIKit MessageUI MetalFX CoreNFC HomeKit CryptoKit ScreenTime NewsstandKit MLCompute NaturalLanguage CoreVideo MetalKit OSLog PDFKit CoreText UniformTypeIdentifiers IOKit ManagedSettings AVFoundation Accelerate DeviceCheck ImageIO BackgroundTasks FamilyControls ClockKit CoreBluetooth ThreadNetwork SensorKit Security Contacts CarPlay ExtensionFoundation RealityKit PhotosUI RoomPlan ReplayKit IOSurface SpriteKit MobileCoreServices IntentsUI QuickLookThumbnailing CoreMedia BusinessChat Intents ColorSync VideoSubscriberAccount PencilKit ManagedSettingsUI CoreServices HealthKit MultipeerConnectivity BackgroundAssets WebKit NotificationCenter SystemConfiguration GameController CoreTelephony ActivityKit AVFAudio AssetsLibrary AudioUnit FileProvider DeviceActivity Social IdentityLookup Matter CoreImage CoreAudio MusicKit DeviceDiscoveryExtension MediaSetup AutomatedDeviceEnrollment CoreAudioKit ExposureNotification ClassKit VisionKit SwiftUI Combine ModelIO PHASE SharedWithYou OpenGLES MetalPerformanceShadersGraph CreateMLComponents Accounts FileProviderUI ShazamKit CarKey RealityFoundation QuickLook AppIntents AuthenticationServices WeatherKit DataDetection AudioToolbox NearbyInteraction ContactsUI CoreSpotlight LocalAuthentication MatterSupport Foundation AdSupport LocalAuthenticationEmbeddedUI Accessibility HealthKitUI PushKit Vision CoreAudioTypes NetworkExtension ExtensionKit OpenAL EventKit MediaAccessibility Charts iAd MapKit AppTrackingTransparency CoreHaptics CallKit CoreFoundation TabularData CoreMotion AVRouting WidgetKit AVKit AddressBook SoundAnalysis GroupActivities CoreLocation CloudKit SharedWithYouCore CFNetwork Photos JavaScriptCore GameplayKit PushToTalk CoreMIDI Twitter PassKit ImageCaptureCore CoreData GLKit AdServices Messages CryptoTokenKit VideoToolbox SafetyKit UserNotifications DeveloperToolsSupport CoreTransferable EventKitUI SceneKit]
+
+end

data/lib/core/podfilelock.rb

@@ -0,0 +1,17 @@
+require_relative 'my_constants'
+require 'yaml'
+
+module PodfileLock
+  class PodfileLockManager
+    # 读取podfile.lock
+    def self.podfile_lock_content
+      podfile_lock = MyConstants::PODFILE_LOCK
+
+      unless File.exist?(podfile_lock)
+        return {}
+      end
+
+      YAML.load_file(podfile_lock)
+    end
+  end
+end

data/lib/core/reference/project.rb

@@ -0,0 +1,201 @@
+require 'json'
+require_relative '../check/xcodeproj'
+require_relative '../my_constants'
+require_relative '../yaml/yaml_dependencies'
+
+module Project
+  class ProjectManager
+
+    # 生成Debug包内的依赖清单json，并注入到对应target的resources脚本中(仅Debug)
+    # @param hook_context post_install钩子上下文:
+    #        插件hook拿到的是Pod::PostInstallHooksContext(umbrella_targets)，
+    #        Podfile里直接拿到的是Pod::Installer(aggregate_targets)，两种都兼容
+    def self.dependency_manifest(hook_context)
+      CocoaPods::Yaml.log.step("依赖清单json生成(仅Debug入包)")
+
+      yaml_dep = Pod::YamlDependencies.new
+      records = yaml_dep.build_dependency_records
+
+      # 各target实际安装的组件根名(TRIM_UNUSED_POD裁剪后为真实子集)
+      installed_map = extract_installed_map(hook_context)
+      if installed_map.empty?
+        CocoaPods::Yaml.log.warn("未获取到target实际安装信息，跳过依赖清单生成")
+        return
+      end
+
+      records.each do |target_name, pod_records|
+        support_dir = "#{Dir.pwd}/Pods/Target Support Files/Pods-#{target_name}"
+        next unless File.directory?(support_dir)
+
+        installed = installed_map[target_name]
+        # 聚合target不存在(该target没有任何pod)时不产出清单
+        next if installed.nil?
+
+        # 按组件根名去重(子组件只保留一条)，并过滤掉未实际安装的组件
+        merged_records = []
+        did_merge = {}
+        pod_records.each do |record|
+          root_name = record['pod'].to_s.split('/').first
+          next unless installed.include?(root_name)
+          next if did_merge[root_name]
+          did_merge[root_name] = true
+          merged_records << record
+        end
+        merged_records.sort_by! { |record| record['pod'].to_s.downcase }
+
+        json_name = yaml_dep.target_json_name(target_name)
+        manifest = {
+          'target' => target_name,
+          'cocoapods-yaml' => CocoaPods::Yaml::VERSION,
+          'pods' => merged_records,
+        }
+        json_path = File.join(support_dir, json_name)
+        File.open(json_path, 'w') { |file| file.write(JSON.pretty_generate(manifest)) }
+
+        resource_shell_path = File.join(support_dir, "Pods-#{target_name}-resources.sh")
+        inject_manifest_resource(resource_shell_path, target_name, json_name)
+      end
+    end
+
+    # 从两种钩子上下文中提取 target名 => 实际安装组件根名列表
+    # Pod::PostInstallHooksContext(插件hook)用umbrella_targets；
+    # Pod::Installer(Podfile内post_install)用aggregate_targets
+    def self.extract_installed_map(hook_context)
+      installed_map = {}
+      return installed_map unless hook_context
+
+      if hook_context.respond_to?(:umbrella_targets)
+        hook_context.umbrella_targets.each do |umbrella|
+          label = umbrella.cocoapods_target_label.to_s
+          target_name = label.sub(/^Pods-/, '')
+          installed_map[target_name] = umbrella.specs.map { |spec| spec.root.name }.uniq
+        end
+      elsif hook_context.respond_to?(:aggregate_targets)
+        hook_context.aggregate_targets.each do |aggregate_target|
+          target_name = aggregate_target.name.sub(/^Pods-/, '')
+          installed_map[target_name] = aggregate_target.specs.map { |spec| spec.root.name }.uniq
+        end
+      end
+      installed_map
+    end
+
+    # 仅往Debug块注入清单资源，Release包不带任何依赖清单
+    def self.inject_manifest_resource(file_path, target_name, json_name)
+      return unless File.exist?(file_path)
+
+      content = IO.read(file_path)
+      return if content.include?(json_name)
+
+      resource_line = "  install_resource \"${PODS_ROOT}/Target Support Files/Pods-#{target_name}/#{json_name}\"\n"
+      debug_marker = 'if [[ "$CONFIGURATION" == "Debug" ]]; then'
+
+      lines = content.lines
+      inserted = false
+      lines.each_with_index do |line, index|
+        next unless line.include?(debug_marker)
+        lines.insert(index + 1, resource_line)
+        inserted = true
+        break
+      end
+
+      unless inserted
+        CocoaPods::Yaml.log.warn("未找到Debug配置块，#{json_name}未注入(#{File.basename(file_path)})")
+        return
+      end
+
+      File.open(file_path, 'w') { |file| file.write(lines.join) }
+    end
+
+
+    # 将yaml文件加入Pods工程引用(仅为Xcode内可见可编辑)，并把本地覆盖文件加入git忽略
+    def self.yaml_reference
+      CocoaPods::Yaml.log.step("yaml文件引用添加")
+      self.add_yaml
+      self.add_local_yaml_ignore
+    end
+
+    def self.add_yaml
+      yaml_dep = Pod::YamlDependencies.new
+      project_manager = XCProject::XcodeprojManager.share_manager
+      pods_project = project_manager.get_pods_project
+      return unless pods_project
+
+      yaml_files = dependency_yaml_files(yaml_dep, project_manager)
+
+      did_add = []
+      pods_project.main_group.children.each {|child|
+        did_add << child.display_name
+      }
+
+      yaml_files.each do |yaml_file|
+        unless did_add.include?(yaml_file)
+          path = "#{Dir.pwd}/#{yaml_file}"
+          pods_project.new_file(path)
+        end
+      end
+
+      pods_project.sort(:groups_position => :below)
+
+      # 依赖相关文件固定排在最前: Podfile、LocalDependencies.yaml、各target依赖文件(按工程target顺序)
+      preferred_names = ['Podfile'] + yaml_files
+      reorder_preferred_files(pods_project, preferred_names)
+
+      pods_project.save
+    end
+
+    # 将指定名称的文件引用移动到main_group最前面(保持preferred_names给定的顺序)，其余文件顺序不变
+    def self.reorder_preferred_files(pods_project, preferred_names)
+      group = pods_project.main_group
+      children = group.children
+      preferred = preferred_names.map { |name| children.find { |child| child.display_name == name } }.compact
+      return if preferred.empty?
+      group.children.replace(preferred + (children - preferred))
+    end
+
+    # 需要在Pods工程中可见的yaml文件: 本地覆盖文件 + 各target依赖文件
+    def self.dependency_yaml_files(yaml_dep, project_manager)
+      files = []
+      local_name = yaml_dep.local_yaml_name
+      files << local_name if File.exist?(local_name)
+
+      project_manager.get_app_targets.each do |target|
+        next unless yaml_dep.integratable_target?(target)
+        yaml_name = yaml_dep.target_yaml_name(target.name)
+        files << yaml_name if File.exist?(yaml_name)
+      end
+      files
+    end
+
+    # 把本地覆盖文件添加到忽略文件中
+    def self.add_local_yaml_ignore
+
+      gitignore = ".gitignore"
+      local_yaml = MyConstants::LOCAL_DEPENDENCIES_YAML
+
+      contain = false
+      gitignore_path = "#{Dir.pwd}/#{gitignore}"
+      if File.exist?(gitignore_path)
+        safe_readlines(gitignore_path).each do |line|
+          # include?兼容已有条目带/前缀、子目录路径、行尾注释等不同形态，避免重复追加
+          contain = true if line.include?(local_yaml)
+          break if contain
+        end
+      end
+
+      unless contain
+        File.open(gitignore_path, 'a+') { |file|
+          file.write("\n#{local_yaml}\n")
+        }
+      end
+    end
+
+    # 容错读取文件行：历史工程的.gitignore可能是CRLF行尾或GBK等非UTF-8编码。
+    # 直接给IO.readlines传encoding: 'utf-8'在内外编码相同时不会转码，非法字节仍会透传，
+    # 先按二进制读取再显式做一次同编码转换替换非法字节，避免后续处理抛invalid byte sequence
+    def self.safe_readlines(file_path)
+      content = File.read(file_path, mode: 'rb')
+      content.encode!('UTF-8', 'UTF-8', invalid: :replace, undef: :replace, replace: '?')
+      content.lines
+    end
+  end
+end

data/lib/core/reference/unused.rb

@@ -0,0 +1,30 @@
+require_relative '../my_constants'
+require_relative '../yaml/yaml_dependencies'
+
+module Unused
+  class UnusedManager
+
+    # 打印未被引用的依赖库
+    def self.check_unused
+
+      yaml_dep = Pod::YamlDependencies.new
+      log = CocoaPods::Yaml.log
+
+      if yaml_dep.trim_unused_pod?
+        msg =  "💚 当前已开启未使用依赖裁剪，请关注上方日志 '下载依赖...'部分内容。"
+        msg += "\n   #{MyConstants::LOCAL_DEPENDENCIES_YAML}文件内的依赖库不会被裁剪。如需关闭，有2种方式任选其一:"
+        msg += "\n   1. 在#{MyConstants::LOCAL_DEPENDENCIES_YAML}中把最外层 TRIM_UNUSED_POD 设置为false，然后重新pod install"
+        msg += "\n   2. 执行 pod install/update --full 可单次关闭"
+        log.info(msg, :green)
+      else
+        msg = "💛 检测到你未开启未使用依赖裁剪。开发模式下可开启，移除未被引用的依赖库以加速编译，有2种方式任选其一:"
+        msg += "\n   1. 在#{MyConstants::LOCAL_DEPENDENCIES_YAML}中把最外层 TRIM_UNUSED_POD 设置为true，然后重新pod install"
+        msg += "\n   2. 执行 pod install/update --trim 可单次开启"
+        log.info(msg, :yellow)
+      end
+      log.info('')
+
+    end
+
+  end
+end

data/lib/core/setup/podfile_setup.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'time'
+require_relative '../yaml/yaml_dependencies'
+
+module CocoaPods
+  module Yaml
+    # Podfile初始化: 生成接入cocoapods-yaml的模板Podfile
+    class PodfileSetup
+      TEMPLATE = <<~'PODFILE'
+      # frozen_string_literal: true
+      # cocoapods-yaml 插件会被CocoaPods自动加载，无需require；
+      # 若 pod 命令提示找不到 yaml_dependencies!，请执行: gem install cocoapods-yaml
+
+      platform :ios, '15.0'
+
+      yaml_dependencies! do |target_name|
+        # target_name: 当前集成的target名称(App/扩展)，每个声明了依赖的target回调一次
+        # 可按target定制，例如:
+        #   use_frameworks! :linkage => :static if target_name == 'ShareExtension'
+        use_frameworks!
+      end
+
+      post_install do |installer|
+        installer.pods_project.targets.each do |target|
+          target.build_configurations.each do |config|
+            config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '$(inherited)'
+          end
+        end
+      end
+      PODFILE
+
+    # pod yaml init: 显式初始化
+    # 无Podfile直接生成；已有Podfile但未接入时先备份再替换
+    def self.run
+      setup = new
+      unless setup.xcodeproj?
+        CocoaPods::Yaml.log.error('当前目录未找到.xcodeproj工程文件，请在iOS工程根目录执行 pod yaml init')
+        exit 1
+      end
+
+      if File.exist?('Podfile')
+        if setup.integrated?
+          CocoaPods::Yaml.log.info('当前工程已接入cocoapods-yaml，无需初始化')
+          return
+        end
+        setup.backup_podfile
+        setup.write_template
+      else
+        setup.write_template
+      end
+
+      setup.generate_yamls
+    end
+
+    # pod install/update 时自动初始化: 仅限无Podfile的零风险场景
+    # 已有Podfile但未接入时只引导，不自动替换
+    def self.auto_on_install
+      setup = new
+      return unless setup.xcodeproj?
+
+      if File.exist?('Podfile')
+        unless setup.integrated?
+          CocoaPods::Yaml.log.warn('检测到Podfile未接入cocoapods-yaml，执行 pod yaml init 可备份后生成模板(不会自动替换现有Podfile)')
+        end
+        return
+      end
+
+      setup.write_template
+      CocoaPods::Yaml.log.detail('未找到Podfile，已自动生成接入cocoapods-yaml的模板Podfile，依赖yaml文件将在解析时生成')
+    end
+
+    # 当前目录是否存在xcodeproj
+    def xcodeproj?
+      Dir.glob('*.xcodeproj').any?
+    end
+
+    # Podfile是否已接入yaml_dependencies!
+    def integrated?
+      File.read('Podfile').include?('yaml_dependencies!')
+    rescue StandardError
+      false
+    end
+
+    def backup_podfile
+      backup_name = "Podfile.bak.#{Time.now.strftime('%Y%m%d%H%M%S')}"
+      FileUtils.cp('Podfile', backup_name)
+      CocoaPods::Yaml.log.detail("已备份原Podfile为: #{backup_name}")
+    end
+
+    def write_template
+      File.write('Podfile', TEMPLATE)
+      CocoaPods::Yaml.log.detail('已生成模板Podfile')
+    end
+
+    # 生成本地覆盖文件与各target依赖文件模板
+    def generate_yamls
+      yaml_dep = Pod::YamlDependencies.new
+      yaml_dep.init_main_targets
+      yaml_dep.generate_yaml
+    rescue StandardError => e
+      CocoaPods::Yaml.log.warn("依赖yaml模板生成失败(不影响已生成的Podfile): #{e.message}")
+    end
+    end
+  end
+end