pindo 5.18.17 → 5.19.1

data/lib/pindo/module/task/model/git/git_tag_task.rb

@@ -12,7 +12,7 @@ module Pindo
         :git_tag
       end
 
-      # 重试配置：失败后重试 1 次
+      # 重试配置：失败后重试 2 次（共 3 次尝试）
       def self.default_retry_count
         2
       end
@@ -39,7 +39,7 @@ module Pindo
       protected
 
       def do_work
-        # 检查是否为 Git 仓库，如果不是则直接成功返回
+        # 检查是否为 Git 仓库，如果不是则直接成功返回（非 Git 仓库目录下跳过打 tag）
         unless valid_git_repository?
           Funlog.instance.fancyinfo_warning("当前目录不是Git仓库，跳过Git打Tag")
           return {
@@ -51,93 +51,108 @@ module Pindo
 
         root_dir = @git_root_path
         git_repo_helper = Pindo::GitRepoHelper.share_instance
-        stash_saved = false
         stash_name = "pindo_stash_#{Time.now.strftime('%Y%m%d%H%M%S')}_#{rand(1000)}"
         coding_branch = Pindo::GitHandler.git!(%W(-C #{root_dir} rev-parse --abbrev-ref HEAD)).strip
+        git_commit_data = get_data_param_by_key(:git_commit)
+        stash_saved = false
 
         begin
-          # 1. 检查工作目录，不干净则 stash
-          status = Pindo::GitHandler.git!(%W(-C #{root_dir} status --porcelain)).strip
-          unless status.empty?
-            Funlog.instance.fancyinfo_update("工作目录有未提交更改，暂存到 stash: #{stash_name}")
-            Pindo::GitHandler.git!(%W(-C #{root_dir} stash push -u -m #{stash_name}))
-            stash_saved = true
-          end
-
-          # 2. 从 GitCommitTask 获取参数（必须在合并之前，确保 release_branch 等参数正确）
-          git_commit_data = get_data_param_by_key(:git_commit)
-          if git_commit_data && git_commit_data[:task_param]
-            param = git_commit_data[:task_param]
-            @release_branch = param[:release_branch] if param[:release_branch]
-            @tag_pre = param[:tag_pre] if param[:tag_pre]
-            @tag_type = param[:tag_type] if param[:tag_type]
-            @ver_inc = param[:ver_inc] if param[:ver_inc]
-          end
-
-          # 3. 合并到发布分支（使用已回填的 @release_branch）
-          if coding_branch != @release_branch
-            Pindo::GitHandler.merge_branches(
-              project_dir: root_dir,
-              source_branch: coding_branch,
-              target_branch: @release_branch,
-              sync_branches: true  # 双向合并，确保两分支完全同步
-            )
-          end
-
-          # 4. 获取版本信息
-          if git_commit_data && git_commit_data[:task_param] &&
-             git_commit_data[:task_param][:build_version] && git_commit_data[:task_param][:build_number]
-            @build_version = git_commit_data[:task_param][:build_version]
-            @build_number = git_commit_data[:task_param][:build_number]
-            Funlog.instance.fancyinfo_success("使用 GitCommitTask 的版本号: #{@build_version}, Build: #{@build_number}, Tag前缀: #{@tag_pre}, Tag类型: #{@tag_type}")
-
-          # 降级：自己计算（向后兼容或 GitCommitTask 无有效数据）
-          else
-            @build_number, @commit_hash = git_repo_helper.get_build_number_from_commit(project_dir: root_dir)
-            @build_version = git_repo_helper.calculate_build_version(
-              project_dir: root_dir,
-              tag_prefix: @tag_pre,
-              create_tag_type: @tag_type,
-              version_increase_type: @ver_inc
-            )
-            commit_short = @commit_hash ? @commit_hash[0..7] : "unknown"
-            Funlog.instance.fancyinfo_warning("未找到 GitCommitTask 依赖，降级为自己计算版本号: #{@build_version}, Build: #{@build_number}, Commit: #{commit_short}")
-          end
-
-          # 4. 创建并推送 Tag
+          # 1. 工作目录不干净则暂存
+          stash_saved = stash_if_dirty(root_dir, stash_name)
+
+          # 2. 从 GitCommitTask 回填参数（须在合并之前，确保 release_branch 等正确）
+          backfill_params_from_commit_task(git_commit_data)
+
+          # 3. 合并到发布分支
+          merge_to_release_branch(root_dir, coding_branch)
+
+          # 4. 解析版本号
+          resolve_build_version(root_dir, git_commit_data, git_repo_helper)
+
+          # 5. 创建并推送 Tag
           tag_name = "#{@tag_pre}#{@build_version}"
           git_repo_helper.create_and_push_tag(
             project_dir: root_dir,
             tag_name: tag_name,
             tag_type: @tag_type
           )
-
         ensure
-          # 5. 还原 stash
-
-          if stash_saved
-            begin
-              # 查找指定名字的 stash
-              stash_list = Pindo::GitHandler.git!(%W(-C #{root_dir} stash list)).strip
-              matched_line = stash_list.lines.find { |l| l.include?(stash_name) }
-
-              if matched_line && (stash_id = matched_line.match(/(stash@\{\d+\})/)&.[](1))
-                # 先应用 stash（不删除）
-                Pindo::GitHandler.git!(%W(-C #{root_dir} stash apply #{stash_id}))
-                # 应用成功后再删除 stash
-                Pindo::GitHandler.git!(%W(-C #{root_dir} stash drop #{stash_id}))
-                Funlog.instance.fancyinfo_success("已还原 stash: #{stash_name} (#{stash_id})")
-              else
-                Funlog.instance.fancyinfo_warning("未找到名为 #{stash_name} 的 stash，请手动检查")
-              end
-            rescue => e
-              # 如果应用失败（通常是有冲突），stash 仍然保留，用户可以手动处理
-              Funlog.instance.fancyinfo_warning("stash 还原时发生冲突: #{e.message}")
-              Funlog.instance.fancyinfo_warning("stash 已保留，请手动执行 'git stash pop' 处理冲突")
-              # 不抛出异常，任务仍然标记为成功（因为 tag 已经创建成功）
-            end
-          end
+          # 6. 还原 stash
+          restore_stash(root_dir, stash_name) if stash_saved
+        end
+      end
+
+      private
+
+      # 工作目录有未提交更改则暂存，返回是否已暂存
+      def stash_if_dirty(root_dir, stash_name)
+        status = Pindo::GitHandler.git!(%W(-C #{root_dir} status --porcelain)).strip
+        return false if status.empty?
+
+        Funlog.instance.fancyinfo_update("工作目录有未提交更改，暂存到 stash: #{stash_name}")
+        Pindo::GitHandler.git!(%W(-C #{root_dir} stash push -u -m #{stash_name}))
+        true
+      end
+
+      # 从 GitCommitTask 回填 release_branch / tag_pre / tag_type / ver_inc
+      def backfill_params_from_commit_task(git_commit_data)
+        return unless git_commit_data && git_commit_data[:task_param]
+
+        param = git_commit_data[:task_param]
+        @release_branch = param[:release_branch] if param[:release_branch]
+        @tag_pre = param[:tag_pre] if param[:tag_pre]
+        @tag_type = param[:tag_type] if param[:tag_type]
+        @ver_inc = param[:ver_inc] if param[:ver_inc]
+      end
+
+      # 将编码分支双向合并到发布分支，确保两分支同步到同一节点
+      def merge_to_release_branch(root_dir, coding_branch)
+        return if coding_branch == @release_branch
+
+        Pindo::GitHandler.merge_branches(
+          project_dir: root_dir,
+          source_branch: coding_branch,
+          target_branch: @release_branch,
+          sync_branches: true  # 双向合并，确保两分支完全同步
+        )
+      end
+
+      # 解析构建版本号：优先用 GitCommitTask 的，否则自己计算（向后兼容）
+      def resolve_build_version(root_dir, git_commit_data, git_repo_helper)
+        if git_commit_data && git_commit_data[:task_param] &&
+           git_commit_data[:task_param][:build_version] && git_commit_data[:task_param][:build_number]
+          @build_version = git_commit_data[:task_param][:build_version]
+          @build_number = git_commit_data[:task_param][:build_number]
+          Funlog.instance.fancyinfo_success("使用 GitCommitTask 的版本号: #{@build_version}, Build: #{@build_number}, Tag前缀: #{@tag_pre}, Tag类型: #{@tag_type}")
+        else
+          @build_number, @commit_hash = git_repo_helper.get_build_number_from_commit(project_dir: root_dir)
+          @build_version = git_repo_helper.calculate_build_version(
+            project_dir: root_dir,
+            tag_prefix: @tag_pre,
+            create_tag_type: @tag_type,
+            version_increase_type: @ver_inc
+          )
+          commit_short = @commit_hash ? @commit_hash[0..7] : "unknown"
+          Funlog.instance.fancyinfo_warning("未找到 GitCommitTask 依赖，降级为自己计算版本号: #{@build_version}, Build: #{@build_number}, Commit: #{commit_short}")
+        end
+      end
+
+      # 还原之前暂存的 stash；冲突时保留 stash 并告警，不抛异常（tag 已创建成功）
+      def restore_stash(root_dir, stash_name)
+        stash_list = Pindo::GitHandler.git!(%W(-C #{root_dir} stash list)).strip
+        matched_line = stash_list.lines.find { |l| l.include?(stash_name) }
+
+        if matched_line && (stash_id = matched_line.match(/(stash@\{\d+\})/)&.[](1))
+          # 先应用 stash（不删除），成功后再删除
+          Pindo::GitHandler.git!(%W(-C #{root_dir} stash apply #{stash_id}))
+          Pindo::GitHandler.git!(%W(-C #{root_dir} stash drop #{stash_id}))
+          Funlog.instance.fancyinfo_success("已还原 stash: #{stash_name} (#{stash_id})")
+        else
+          Funlog.instance.fancyinfo_warning("未找到名为 #{stash_name} 的 stash，请手动检查")
         end
+      rescue => e
+        Funlog.instance.fancyinfo_warning("stash 还原时发生冲突: #{e.message}")
+        Funlog.instance.fancyinfo_warning("stash 已保留，请手动执行 'git stash pop' 处理冲突")
       end
 
     end

data/lib/pindo/module/task/model/jps/jps_workflow_message_task.rb

@@ -15,6 +15,11 @@ module Pindo
         :jps_workflow_message
       end
 
+      # 工作流消息失败重试 1 次（覆盖 JPSTask 默认的重试 3 次）
+      def self.default_retry_count
+        1
+      end
+
       # 初始化工作流消息发送任务
       # @param options [Hash] 选项
       # @option options [String] :git_commit_id Git commit SHA（可选，从依赖任务获取）
@@ -70,17 +75,10 @@ module Pindo
             workflow_id: @workflow_id
           }
         rescue => e
-          # 外层错误保护：消息发送失败不应影响整体流程
-          puts "  ⚠️  JPS 工作流消息发送发生错误: #{e.message}"
+          # 工作流消息是终端任务，失败需明确报错中断（不再伪造 success）
+          puts "  ❌ JPS 工作流消息发送失败: #{e.message}"
           puts "  ⚠️  错误堆栈: #{e.backtrace.first(3).join("\n           ")}" if ENV['PINDO_DEBUG'] && e.backtrace
-          puts "  ℹ️  消息发送失败不影响主流程\n"
-
-          # 消息发送失败不抛出异常，返回成功但带警告
-          {
-            success: true,
-            warning: e.message,
-            git_commit_id: @git_commit_id
-          }
+          raise Informative, "JPS 工作流消息发送失败: #{e.message}"
         end
       end
 

data/lib/pindo/module/task/model/unity/unity_export_task.rb

@@ -1,5 +1,6 @@
 require 'pindo/module/task/model/unity_task'
 require 'pindo/base/funlog'
+require 'json'
 
 module Pindo
   module TaskSystem
@@ -18,6 +19,7 @@ module Pindo
       #   - :project_path [String] Unity 项目路径（默认当前目录）
       #   - :export_path [String] 导出路径（nil 表示自动检测）
       #   - :deploy_mode [String] 部署模式 ('dev', 'adhoc', 'release')，默认 'dev'
+      #   - :app_config [Hash] 需写入工程 AppConfig 的键值（传入则在导出前先改写 AppConfig）
       #   - :context [Hash] 上下文信息（如 index_count）
       def initialize(platform, options = {})
         @platform = platform
@@ -26,6 +28,7 @@ module Pindo
         @index_count = options[:context] ? options[:context][:index_count] : nil
         @export_path = options[:export_path]  # 可由参数传入，nil 表示自动检测
         @deploy_mode = options[:deploy_mode] || 'dev'  # 部署模式：dev/adhoc/release，默认 dev
+        @app_config = options[:app_config]  # 需写入 AppConfig 的键值，nil/空表示跳过
 
         name = case platform
                when 'ios', 'ipa'
@@ -57,6 +60,9 @@ module Pindo
       protected
 
       def do_work
+        # 若传入了配置参数，先改写工程内的 AppConfig
+        update_app_config_file if @app_config && !@app_config.empty?
+
         # 获取 Unity 版本
         project_unity_version = get_unity_version
 
@@ -106,6 +112,44 @@ module Pindo
 
       private
 
+      # 使用传入的配置改写 Unity 工程内的 AppConfig（TextAsset JSON）
+      # 仅覆盖 @app_config 中提供的键，其余键保持原值
+      def update_app_config_file
+        app_config_file = File.join(@unity_root_path, "Assets", "Resources", "AppConfig", "AppConfig.json")
+        unless File.exist?(app_config_file)
+          Funlog.warning("未找到 AppConfig 文件，跳过 AppConfig 更新：#{app_config_file}")
+          return
+        end
+
+        puts "更新 AppConfig: #{app_config_file}"
+
+        begin
+          app_config_json = JSON.parse(File.read(app_config_file))
+        rescue JSON::ParserError => e
+          Funlog.warning("AppConfig 不是合法 JSON，跳过更新：#{e.message}")
+          return
+        end
+
+        changed = false
+        @app_config.each do |key, value|
+          next if value.nil? || value.to_s.strip.empty?
+          new_value = value.to_s.strip
+          old_value = app_config_json[key]
+          next if old_value.to_s == new_value
+
+          app_config_json[key] = new_value
+          puts "  ✓ #{key}: #{old_value} → #{new_value}"
+          changed = true
+        end
+
+        if changed
+          File.open(app_config_file, "w") { |f| f.write(JSON.pretty_generate(app_config_json)) }
+          puts "✅ AppConfig 更新完成\n"
+        else
+          puts "AppConfig 无需更新（值一致）\n"
+        end
+      end
+
       # 导出 iOS
       def export_ios
         platform = 'iOS'

data/lib/pindo/module/task/pindo_task.rb

@@ -446,9 +446,9 @@ module Pindo
         end
       end
 
-      # 计算当前重试次数
+      # 计算当前重试次数（调用时 @retry_count 已递减，无需再 +1）
       def current_retry_attempt
-        @max_retry_count - @retry_count + 1
+        @max_retry_count - @retry_count
       end
 
       # 立即重试

data/lib/pindo/module/task/task_manager.rb

@@ -118,12 +118,19 @@ module Pindo
         # 输出执行摘要
         @reporter.print_execution_summary
 
-        # 检查失败任务，有失败则抛出异常（确保进程返回非零退出码）
-        report = execution_report
-        if report[:failed] > 0
-          failed_tasks = @queue.completed_snapshot.select { |t| t.status == TaskStatus::FAILED }
-          failed_names = failed_tasks.map(&:name).join(', ')
-          raise Informative, "#{report[:failed]} 个任务执行失败: #{failed_names}"
+        # 失败闸门：FAILED / CANCELLED / 残留 PENDING（依赖阻塞等导致从未执行）都视为
+        # 「未成功完成」，统一抛异常确保进程非零退出码，避免任务没跑成却静默成功
+        completed = @queue.completed_snapshot
+        failed_tasks = completed.select { |t| t.status == TaskStatus::FAILED }
+        cancelled_tasks = completed.select { |t| t.status == TaskStatus::CANCELLED }
+        unfinished_tasks = @queue.pending_snapshot
+
+        if failed_tasks.any? || cancelled_tasks.any? || unfinished_tasks.any?
+          parts = []
+          parts << "失败: #{failed_tasks.map(&:name).join(', ')}" if failed_tasks.any?
+          parts << "取消: #{cancelled_tasks.map(&:name).join(', ')}" if cancelled_tasks.any?
+          parts << "未执行: #{unfinished_tasks.map(&:name).join(', ')}" if unfinished_tasks.any?
+          raise Informative, "存在未成功完成的任务 —— #{parts.join('；')}"
         end
       end
 
@@ -138,6 +145,7 @@ module Pindo
           completed: completed.count,
           success: completed.count { |t| t.status == TaskStatus::SUCCESS },
           failed: completed.count { |t| t.status == TaskStatus::FAILED },
+          cancelled: completed.count { |t| t.status == TaskStatus::CANCELLED },
           tasks: (pending + completed).map do |task|
             {
               id: task.id,

data/lib/pindo/module/task/task_reporter.rb

@@ -41,12 +41,57 @@ module Pindo
           end
         end
 
+        # 按依赖拓扑排序展示真实执行顺序
+        ordered = topological_execution_order(@queue.pending_snapshot)
+        is_serial = strategy.respond_to?(:name) && strategy.name.include?("串行")
+        puts "\e[34m"
+        if is_serial
+          puts "\e[34m" + "  实际执行顺序:"
+        else
+          puts "\e[34m" + "  执行顺序预览（并发模式下实际顺序受运行时调度影响）:"
+        end
+        ordered.each_with_index do |task, index|
+          puts "\e[34m" + "    #{index + 1}. #{task.name}"
+        end
+
         puts "\e[34m"
         puts "\e[34m" + "  总计: #{@queue.pending_count} 个任务"
         puts "\e[34m" + "=" * 60 + "\e[0m"
         puts "\n"
       end
 
+      # 按依赖关系生成执行顺序（贪心拓扑排序，模拟串行调度：
+      # 每轮取「入队顺序中第一个依赖已满足」的任务），与串行实际执行顺序一致
+      # @param tasks [Array<PindoTask>] 待排序任务（入队顺序）
+      # @return [Array<PindoTask>] 按执行顺序排列的任务
+      def topological_execution_order(tasks)
+        all_ids = tasks.map(&:id)
+        remaining = tasks.dup
+        completed_ids = []
+        ordered = []
+
+        until remaining.empty?
+          index = remaining.index do |task|
+            task.dependencies.all? do |dep_id|
+              # 依赖已完成，或依赖不在本批任务中（视为已提前完成）
+              completed_ids.include?(dep_id) || !all_ids.include?(dep_id)
+            end
+          end
+
+          # 存在循环依赖或依赖缺失，剩余任务按原顺序追加并结束
+          if index.nil?
+            ordered.concat(remaining)
+            break
+          end
+
+          task = remaining.delete_at(index)
+          completed_ids << task.id
+          ordered << task
+        end
+
+        ordered
+      end
+
       # 输出任务执行标题
       # @param task [PindoTask] 任务对象
       def print_task_title(task)

data/lib/pindo/module/unity/nuget_helper.rb

@@ -505,9 +505,8 @@ module Pindo
         puts "   使用工具: nuget pack"
         puts
 
-        cmd = "cd \"#{package_dir}\" && nuget pack \"#{File.basename(nuspec_file)}\" -OutputDirectory \"#{output_dir}\""
-
-        success = system(cmd)
+        # 数组参数 + chdir，避免路径中的 shell 元字符注入
+        success = system("nuget", "pack", File.basename(nuspec_file), "-OutputDirectory", output_dir, chdir: package_dir)
 
         unless success
           raise Informative, "NuGet 打包失败，请检查 .nuspec 文件格式"
@@ -573,10 +572,8 @@ module Pindo
         begin
           # 查找是否存在与 nuspec 版本匹配的 tag（支持 v1.1.3, V1.1.3, 1.1.3 等格式）
           matching_tag = nil
-          temp_dir = Dir.pwd
-          Dir.chdir(git_root)
 
-          # 获取所有 tags
+          # 获取所有 tags（命令已带 -C，无需 chdir）
           all_tags = Pindo::GitHandler.git!(%W(-C #{git_root} tag -l)).split("\n")
 
           # 查找匹配当前版本的 tag（不区分大小写，支持 v 前缀）
@@ -585,17 +582,12 @@ module Pindo
             tag_version.downcase == nuspec_version.downcase
           end
 
-          Dir.chdir(temp_dir)
-
           # 确定获取哪个范围的 commits
           git_range = if matching_tag
             # 找到匹配的 tag，获取前一个 tag 到这个 tag 的 commits
             puts "📝 找到版本 tag: #{matching_tag}，生成该版本的 release notes..."
 
-            temp_dir = Dir.pwd
-            Dir.chdir(git_root)
-
-            # 获取所有 tags 并按版本号排序
+            # 获取所有 tags 并按版本号排序（命令已带 -C，无需 chdir）
             all_tags = Pindo::GitHandler.git!(%W(-C #{git_root} tag -l)).split("\n")
             sorted_tags = all_tags.sort_by do |tag|
               version_str = tag.gsub(/^(v|V|release[\s_-]*)/i, '')
@@ -609,8 +601,6 @@ module Pindo
               prev_tag = sorted_tags[tag_index - 1]
             end
 
-            Dir.chdir(temp_dir)
-
             if prev_tag
               "#{prev_tag}..#{matching_tag}"
             else
@@ -635,10 +625,7 @@ module Pindo
             end
           end
 
-          # 获取 commit messages（包含完整的 body）
-          temp_dir = Dir.pwd
-          Dir.chdir(git_root)
-
+          # 获取 commit messages（包含完整的 body；命令已带 -C，无需 chdir）
           # 使用特殊分隔符来区分不同的 commits
           separator = "---COMMIT-SEPARATOR---"
           commits_raw = Pindo::GitHandler.git!(%W(-C #{git_root} log #{git_range} --pretty=format:%B#{separator}))
@@ -646,8 +633,6 @@ module Pindo
           # 按分隔符拆分成单个 commits
           commits = commits_raw.split(separator).map(&:strip).reject(&:empty?)
 
-          Dir.chdir(temp_dir)
-
           # 过滤只保留符合规范的 commits（支持带 scope 和不带 scope 格式）
           # 匹配格式: feat:, feat(scope):, fix:, fix(api): 等
           conventional_commit_regex = /^(feat|fix|docs|doc|perf|refactor|style|test|chore|revert)(\([^)]+\))?:/i

data/lib/pindo/module/utils/git_repo_helper.rb

@@ -330,53 +330,86 @@ module Pindo
       raise ArgumentError, "项目目录不能为空" if project_dir.nil?
       raise ArgumentError, "tag名称不能为空" if tag_name.nil? || tag_name.empty?
 
+      local_exists = Pindo::GitHandler.local_tag_exists?(local_repo_dir: project_dir, tag_name: tag_name)
+
+      # 建本地 tag 是纯本地操作，不依赖远程可达，网络故障也能留下本地 tag；
+      # 删远程残留与推送一律交给 push_tag_with_verify，推送失败时本地 tag 仍保留，可事后手动补推。
       case tag_type
       when Pindo::CreateTagType::NONE
+        # 不创建 tag
         Funlog.instance.fancyinfo_success("跳过创建 Tag")
-        return nil
-      when Pindo::CreateTagType::RECREATE
-        # 删除旧 tag（本地和远程）
-        if Pindo::GitHandler.remote_tag_exists?(local_repo_dir: project_dir, tag_name: tag_name)
-          Funlog.instance.fancyinfo_update("删除远程 Tag: #{tag_name}")
-          Pindo::GitHandler.git_remote!(project_dir, %W(-C #{project_dir} push origin :refs/tags/#{tag_name}))
-        end
-        if Pindo::GitHandler.local_tag_exists?(local_repo_dir: project_dir, tag_name: tag_name)
-          Funlog.instance.fancyinfo_update("删除本地 Tag: #{tag_name}")
-          Pindo::GitHandler.git!(%W(-C #{project_dir} tag -d #{tag_name}))
+        nil
+      when Pindo::CreateTagType::NEW, Pindo::CreateTagType::RECREATE
+        # 本地 tag 已在 HEAD：无需重建，仅确保推送到远程（RECREATE 在 HEAD 原地重建也是空转，同样适用）
+        if local_exists && Pindo::GitHandler.is_tag_at_head?(git_root_dir: project_dir, tag_name: tag_name)
+          push_tag_with_verify(project_dir: project_dir, tag_name: tag_name)
+          tag_name
+        else
+          # 本地 tag 不存在或不在 HEAD：删旧重建后推送
+          if local_exists
+            Funlog.instance.fancyinfo_update("删除本地旧 Tag: #{tag_name}")
+            Pindo::GitHandler.git!(%W(-C #{project_dir} tag -d #{tag_name}))
+          end
+          Pindo::GitHandler.git!(%W(-C #{project_dir} tag #{tag_name}))
+          Funlog.instance.fancyinfo_success("已创建本地 Tag: #{tag_name}")
+          push_tag_with_verify(project_dir: project_dir, tag_name: tag_name)
+          tag_name
         end
-      when Pindo::CreateTagType::NEW
-        local_exists = Pindo::GitHandler.local_tag_exists?(local_repo_dir: project_dir, tag_name: tag_name)
-        remote_exists = Pindo::GitHandler.remote_tag_exists?(local_repo_dir: project_dir, tag_name: tag_name)
+      else
+        raise ArgumentError, "未知的 tag_type: #{tag_type}"
+      end
+    end
 
-        # 如果 tag 在 HEAD 上，不需要重新创建
-        if local_exists && Pindo::GitHandler.is_tag_at_head?(git_root_dir: project_dir, tag_name: tag_name)
-          if !remote_exists
-            # 本地存在且在 HEAD，但远程不存在，推送到远程
-            Pindo::GitHandler.git_remote!(project_dir, %W(-C #{project_dir} push origin #{tag_name}))
-            Funlog.instance.fancyinfo_success("推送 Tag 到远程: #{tag_name}")
-          else
-            Funlog.instance.fancyinfo_success("Tag 已存在且在 HEAD: #{tag_name}")
+    # 推送 tag 到远程并校验是否真正推送成功，失败则重试
+    # 校验方式为「远程 tag 指向的 commit == 本地 tag commit」，
+    # 一次 ls-remote 同时覆盖「存在性」与「指向正确性」
+    # @param project_dir [String] 仓库目录
+    # @param tag_name [String] tag 名称
+    # @param max_retries [Integer] 最大重试次数（默认 3）
+    # @return [Boolean] 是否推送成功（失败到达上限会 raise）
+    def push_tag_with_verify(project_dir:, tag_name:, max_retries: 3)
+      local_commit = Pindo::GitHandler.git!(%W(-C #{project_dir} rev-parse #{tag_name}^{commit})).strip
+
+      attempt = 0
+      loop do
+        attempt += 1
+        begin
+          # 远程若残留指向不同 commit 的同名 tag，先删除再推送，避免 non-fast-forward 被拒
+          remote_commit = Pindo::GitHandler.remote_tag_commit(local_repo_dir: project_dir, tag_name: tag_name)
+          if remote_commit == local_commit
+            Funlog.instance.fancyinfo_success("已确认 Tag 推送到远程: #{tag_name}")
+            return true
+          elsif remote_commit
+            Funlog.instance.fancyinfo_update("删除远程残留 Tag（远程 #{remote_commit[0..7]} ≠ 本地 #{local_commit[0..7]}）: #{tag_name}")
+            Pindo::GitHandler.git_remote!(project_dir, %W(-C #{project_dir} push origin :refs/tags/#{tag_name}))
           end
-          return tag_name
+
+          Pindo::GitHandler.git_remote!(project_dir, %W(-C #{project_dir} push origin #{tag_name}))
+        rescue => e
+          first_line = e.message.lines.first&.strip
+          Funlog.instance.fancyinfo_warning("推送 Tag 失败（第 #{attempt}/#{max_retries} 次）: #{first_line}")
         end
 
-        # tag 不在 HEAD 上，需要删除后重新创建
-        if remote_exists
-          Funlog.instance.fancyinfo_update("删除远程 Tag: #{tag_name}")
-          Pindo::GitHandler.git_remote!(project_dir, %W(-C #{project_dir} push origin :refs/tags/#{tag_name}))
+        # 校验远程 tag 指向的 commit 是否与本地一致，确认推送成功（探测失败按未确认处理，不中断重试）
+        remote_commit = begin
+          Pindo::GitHandler.remote_tag_commit(local_repo_dir: project_dir, tag_name: tag_name)
+        rescue
+          nil
         end
-        if local_exists
-          Funlog.instance.fancyinfo_update("删除本地 Tag: #{tag_name}")
-          Pindo::GitHandler.git!(%W(-C #{project_dir} tag -d #{tag_name}))
+        if remote_commit && remote_commit == local_commit
+          Funlog.instance.fancyinfo_success("已确认 Tag 推送到远程: #{tag_name}")
+          return true
         end
-        # 继续创建新 tag
-      end
 
-      # 创建并推送 tag
-      Pindo::GitHandler.git!(%W(-C #{project_dir} tag #{tag_name}))
-      Pindo::GitHandler.git_remote!(project_dir, %W(-C #{project_dir} push origin #{tag_name}))
-      Funlog.instance.fancyinfo_success("创建并推送 Tag: #{tag_name}")
-      tag_name
+        if attempt >= max_retries
+          # 本地 tag 已创建，仅远程未确认 —— 保留本地 tag，提示可手动补推
+          Funlog.instance.fancyinfo_warning("本地 Tag 已创建并保留，可稍后手动执行: git push origin #{tag_name}")
+          raise Informative, "Tag 推送失败，已重试 #{max_retries} 次仍未在远程确认: #{tag_name}（本地 Tag 已保留，可手动补推）"
+        end
+
+        Funlog.instance.fancyinfo_update("远程未确认 Tag，#{attempt}s 后重试推送: #{tag_name}")
+        sleep(attempt)
+      end
     end
 
   end