pindo 5.20.3 → 5.20.4

data/lib/pindo/command/web/autobuild.rb

@@ -366,9 +366,13 @@ module Pindo
                       tasks << message_task
                     end
 
-                    # 8. 创建媒体附件上传任务（如果需要，只依赖 Git 提交任务）
-                    if @args_media_flag
-                      # 获取 Git 管理类型的工作流（不同于 HTML 上传的工作流）
+                    # 8. 获取 Git 管理类型的工作流（media、bind、send 共用，不同于 HTML 上传的包工作流）
+                    # commit 记录挂在 Git 工作流下，媒体附件、包绑定、工作流消息都按它定位
+                    git_app_info_obj = nil
+                    git_workflow_info = nil
+                    if @args_media_flag || @args_bind_flag || @args_send_flag
+                      # 取不到就让异常冒泡：media/bind/send 都依赖它，静默跳过会让命令
+                      # 明明没做用户要求的事却以 0 退出
                       git_app_info_obj, git_workflow_info = PgyerHelper.share_instace.prepare_upload(
                         working_directory: config[:project_path],
                         conf: @args_conf,
@@ -376,48 +380,53 @@ module Pindo
                         manage_type: "git"
                       )
 
+                      unless git_app_info_obj && git_workflow_info
+                        raise Informative, "未获取到 Git 类型的工作流；请在 JPS 后台配置 manage_type=git 的工作流"
+                      end
+                    end
+
+                    # 9. 创建媒体附件上传任务（如果需要，依赖 Git 提交/打 Tag 任务）
+                    if @args_media_flag
                       media_upload_task = Pindo::TaskSystem::JPSUploadMediaTask.new(
                         [],  # 空数组，自动从 JPSMedia/ 目录查找
                         config[:project_path],  # upload_path
                         app_info_obj: git_app_info_obj,
                         workflow_info: git_workflow_info,
-                        project_name: nil
+                        project_name: nil,
+                        required: @options[:media] || false  # 仅用户显式 --media 时，找不到文件才算失败
                       )
                       # 依赖 Git 提交任务
                       media_upload_task.dependencies << git_commit_task.id
+                      # 同样依赖 GitTagTask：并发模式下媒体上传可能与 build/tag 并行，
+                      # 不依赖它就会关联到构建前的 commit，与包绑定的 commit 不一致
+                      media_upload_task.dependencies << git_tag_task.id if git_tag_task
                       tasks << media_upload_task
                     end
 
-                    # 9. 创建 Git Commit 绑定任务（如果需要，依赖上传任务）
+                    # 10. 创建 Git Commit 绑定任务（如果需要，依赖上传任务）
                     bind_package_task = nil  # 声明变量以便后续工作流消息任务使用
                     if @args_bind_flag
                       bind_package_task = Pindo::TaskSystem::JPSBindPackageTask.new(
                         nil,  # app_version_list 为 nil，从依赖任务获取
                         project_dir: config[:project_path],
-                        app_info_obj: config[:app_info_obj],
-                        workflow_info: config[:workflow_info],
+                        app_info_obj: git_app_info_obj,      # 使用 Git app_info_obj
+                        workflow_info: git_workflow_info,    # 使用 Git workflow_info
                         project_name: nil
                       )
-                      # 依赖上传任务和 Git 提交任务
+                      # 依赖上传任务和 Git 任务
+                      # GitTagTask 会提交构建注入文件并移动 HEAD，必须依赖它才能拿到 tag 所在的 commit
                       bind_package_task.dependencies << upload_task.id
                       bind_package_task.dependencies << git_commit_task.id
+                      bind_package_task.dependencies << git_tag_task.id if git_tag_task
                       tasks << bind_package_task
                     end
 
-                    # 10. 创建工作流消息任务（如果需要，发送到测试群）
+                    # 11. 创建工作流消息任务（如果需要，发送到测试群）
                     if @args_send_flag
-                      # 获取 Git 工作流信息
-                      git_app_info_obj, git_workflow_info = PgyerHelper.share_instace.prepare_upload(
-                        working_directory: config[:project_path],
-                        conf: @args_conf,
-                        package_type: nil,
-                        manage_type: "git"
-                      )
-
                       workflow_message_task = Pindo::TaskSystem::JPSWorkFlowMessageTask.new(
                         project_id: git_app_info_obj["id"],
-                        workflow_id: git_workflow_info["id"],
-                        branch: 'master',
+                        workflow_id: git_workflow_info[:workflow_id],  # workflow_info 是 symbol key 结构，没有 "id" 键
+                        # branch 不传：由任务从 Git 依赖任务取 resolve 之后的真实发布分支
                         single: true,
                         app_info_obj: git_app_info_obj,
                         workflow_info: git_workflow_info

data/lib/pindo/module/pgyer/pgyerhelper.rb

@@ -1780,69 +1780,113 @@ module Pindo
 
         # 获取特定 commit 已绑定的包 ID
         #
+        # 走 project_package/bind_list（按 projectId 查项目下全部绑定），而不是
+        # commit_log/preview（按 workflowId 过滤）：写入接口 bind_commit 只认全局 commitId、
+        # 且是覆盖式的，查询作用域必须与之一致，否则查漏的平台会在覆盖时被删掉。
+        #
+        # 绑定接口是覆盖式写入，调用方需要把已绑定的包一起提交，因此必须区分
+        # 「确认没有绑定过」和「查不出来」——后者返回空数组会导致已有绑定被静默覆盖丢失。
+        #
         # @param commit_id [String] Git commit SHA（必需）
-        # @param workflow_id [Integer, String] 工作流 ID（必需，API 需要）
-        # @return [Array<String>] 已绑定的包 ID 数组
-        def get_commit_bound_package_ids(commit_id:, workflow_id:)
-            return [] if commit_id.nil? || commit_id.empty?
-            return [] if workflow_id.nil?
+        # @param project_id [String] JPS 项目 ID（必需）
+        # @return [Array<String>, nil] 已绑定的包 ID 数组；查询失败或结构异常时返回 nil
+        def get_commit_bound_package_ids(commit_id:, project_id:)
+            if commit_id.nil? || commit_id.empty?
+                Funlog.instance.fancyinfo_warning("commit_id 为空，无法查询已绑定的包")
+                return nil
+            end
+
+            if project_id.nil? || project_id.to_s.empty?
+                Funlog.instance.fancyinfo_warning("project_id 为空，无法查询已绑定的包")
+                return nil
+            end
 
             begin
-                # 使用 commit_log/preview API 直接查询特定 commit
-                result = @pgyer_client.get_commit_log_preview(
-                    workflowId: workflow_id,
-                    commitIds: [commit_id],
-                    params: { onlyCliff: false }  # 需要完整信息
-                )
+                result = @pgyer_client.get_project_package_bind_list(projectId: project_id)
 
                 # 兼容两种响应格式
                 response_code = result&.dig("code") || result&.dig("meta", "code")
 
-                if result && (response_code == 0 || response_code == 200)
-                    # 从响应中提取 commit 信息
-                    # preview API 可能返回数组或单个对象
-                    commit_data = result&.dig("data")
-                    commit_list = commit_data.is_a?(Array) ? commit_data : [commit_data].compact
-
-                    # 查找匹配的 commit
-                    commit_info = commit_list.find { |item| item && item["commitId"] == commit_id }
-
-                    if commit_info && commit_info["bindVersions"]
-                        # 从 bindVersions 中提取所有平台的 projectPackageId
-                        bind_versions = commit_info["bindVersions"]
-                        package_ids = []
-
-                        # 遍历所有平台（ipa, apk, zip, mac, exe 等）
-                        bind_versions.each do |_platform, version_info|
-                            if version_info && version_info["projectPackageId"]
-                                package_ids << version_info["projectPackageId"]
-                            end
+                unless result && (response_code == 0 || response_code == 200)
+                    error_msg = result&.dig("msg") || result&.dig("meta", "message") || "未知错误"
+                    Funlog.instance.fancyinfo_warning("查询项目 #{project_id} 的包绑定列表失败: #{error_msg}")
+                    debug_dump_bind_list_response(result)
+                    return nil
+                end
+
+                data = result&.dig("data")
+
+                # 接口没有返回数据：项目下没有任何绑定，此时也就不存在会被覆盖丢失的绑定
+                return [] if data.nil?
+
+                # 接口定义返回 map<String, List<ProjectPackagePreviewInfo>>。
+                # 必须先校验类型再判空——[] 和 "" 都 respond_to?(:empty?)，
+                # 先判空会把结构异常的响应误判成「项目下无绑定」，随后覆盖写入清掉已有绑定。
+                # 分组键的语义（commitId / 平台类型）不影响结果：每条记录自带 commitId，按它过滤即可。
+                unless data.is_a?(Hash)
+                    Funlog.instance.fancyinfo_warning("包绑定列表结构异常（#{data.class}），无法确认已有绑定")
+                    debug_dump_bind_list_response(result)
+                    return nil
+                end
+
+                # 空 map：确认项目下没有绑定
+                return [] if data.empty?
+
+                package_ids = []
+                data.each do |group_key, packages|
+                    unless packages.is_a?(Array)
+                        Funlog.instance.fancyinfo_warning("包绑定列表分组 #{group_key} 结构异常（#{packages.class}），无法确认已有绑定")
+                        return nil
+                    end
+
+                    packages.each do |pkg|
+                        unless pkg.is_a?(Hash)
+                            Funlog.instance.fancyinfo_warning("包绑定列表分组 #{group_key} 中存在异常条目，无法确认已有绑定")
+                            return nil
                         end
 
-                        return package_ids.compact.uniq
-                    else
-                        # 如果没有找到或没有绑定信息，返回空数组（可能是首次绑定）
-                        if ENV['PINDO_DEBUG']
-                            puts "[PINDO_DEBUG] Commit #{commit_id[0..7]} 没有绑定信息"
+                        next unless pkg["commitId"] == commit_id
+
+                        # 命中目标 commit 却拿不到包 id：静默跳过会得到残缺列表，
+                        # 覆盖写入时等于把那个包的绑定删掉
+                        package_id = pkg["id"]
+                        if package_id.nil? || package_id.to_s.strip.empty?
+                            Funlog.instance.fancyinfo_warning("Commit #{commit_id[0..7]} 的绑定记录缺少包 id，无法确认已有绑定")
+                            return nil
                         end
-                        return []
-                    end
-                else
-                    # 如果获取失败，返回空数组（不阻止绑定流程）
-                    if ENV['PINDO_DEBUG']
-                        error_msg = result&.dig("msg") || result&.dig("meta", "message") || "未知错误"
-                        puts "[PINDO_DEBUG] 获取 commit 绑定包失败: #{error_msg}"
+
+                        package_ids << package_id
                     end
-                    return []
                 end
+
+                puts "[PINDO_DEBUG] Commit #{commit_id[0..7]} 已绑定 #{package_ids.size} 个包" if ENV['PINDO_DEBUG']
+                package_ids.uniq
             rescue => e
-                # 异常时返回空数组，不阻止绑定流程
-                if ENV['PINDO_DEBUG']
-                    puts "[PINDO_DEBUG] 获取 commit 绑定包异常: #{e.message}"
-                    puts "[PINDO_DEBUG] Backtrace: #{e.backtrace[0..2].join("\n")}"
-                end
-                return []
+                Funlog.instance.fancyinfo_warning("查询 commit 已绑定的包异常: #{e.message}")
+                puts "[PINDO_DEBUG] Backtrace: #{e.backtrace[0..2].join("\n")}" if ENV['PINDO_DEBUG']
+                return nil
+            end
+        end
+
+        # 按白名单输出包绑定列表响应的诊断信息
+        #
+        # ProjectPackagePreviewInfo 里含 cdnUrl、plistUrl、attachFiles、qrCodeUrl 等
+        # 可直接下载安装包的链接，整体 inspect 会把它们写进 CI 日志，
+        # 因此只输出定位问题所需的字段。
+        # @param result [Hash, nil] 接口原始响应
+        def debug_dump_bind_list_response(result)
+            return unless ENV['PINDO_DEBUG']
+
+            code = result&.dig("code") || result&.dig("meta", "code")
+            message = result&.dig("msg") || result&.dig("meta", "message")
+            data = result&.dig("data")
+            summary = if data.is_a?(Hash)
+                data.map { |k, v| [k, v.is_a?(Array) ? "#{v.size} 条" : v.class.to_s] }.to_h
+            else
+                data.class.to_s
             end
+
+            puts "[PINDO_DEBUG] bind_list 响应: code=#{code.inspect} msg=#{message.inspect} data=#{summary.inspect}"
         end
 
         # 获取工作流中已绑定的包 ID（已废弃，请使用 get_commit_bound_package_ids）
@@ -1984,10 +2028,11 @@ module Pindo
         # @param project_id [String] 项目 ID
         # @param workflow_id [Integer] 工作流 ID
         # @param commit_id [String] Git commit SHA
-        # @param branch [String] 分支名（可选，默认 'master'）
+        # @param branch [String, nil] 分支名（可选，nil 时不发送分支字段——传错的分支名
+        #   会让 commit 与分支错误关联，比不传更糟）
         # @param single [Boolean] 是否单个提交（可选，默认 true）
         # @return [Hash] 发送结果
-        def send_workflow_message(project_id:, workflow_id:, commit_id:, branch: 'master', single: true)
+        def send_workflow_message(project_id:, workflow_id:, commit_id:, branch: nil, single: true)
             if project_id.nil? || project_id.empty?
                 Funlog.instance.fancyinfo_error("project_id 不能为空")
                 return { success: false, error: "project_id 不能为空" }
@@ -2009,9 +2054,10 @@ module Pindo
                     workflowId: workflow_id,
                     params: {
                         single: single,
+                        # jpsclient 内部归一化为服务端要求的 branches 数组；nil 时不带该字段
                         branch: branch,
                         commitIds: [commit_id]
-                    }
+                    }.compact
                 )
 
                 # 兼容两种响应格式

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

@@ -122,6 +122,12 @@ module Pindo
         # skip_without_tag 模式：跳过所有 git 同步操作，直接返回
         if @process_type == Pindo::UncommittedFilesProcessType::SKIP_WITHOUT_TAG
           coding_branch = get_current_branch_name
+          # 该模式不合并分支，代码就停在当前分支上，随 task_param 传给工作流消息任务的
+          # 分支必须是当前分支——用默认的 master 或探测出的发布分支，会发出
+          # 「feature 分支的 commit + master 分支名」这种自相矛盾的组合。
+          # detached HEAD 时取不到分支名（current_branch_name 返回 nil），保持 nil，
+          # 让下游工作流消息不带分支发送，而不是把字面量 "HEAD" 当成分支名。
+          @release_branch = Pindo::GitHandler.current_branch_name(local_repo_dir: root_dir)
           @build_number, @commit_hash = git_repo_helper.get_build_number_from_commit(project_dir: root_dir)
 
           # 版本号仍按正常优先级计算，仅"不打 tag / 不升版本"，避免硬编码 0.0.0 污染 build.gradle 与下游上传参数

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

@@ -78,13 +78,19 @@ module Pindo
 
           # 4. 创建并推送 Tag
           tag_name = "#{@tag_pre}#{@build_version}"
-          git_repo_helper.create_and_push_tag(
+          tag_result = git_repo_helper.create_and_push_tag(
             project_dir: root_dir,
             tag_name: tag_name,
             tag_type: @tag_type
           )
+
+          # 5. 固化 commit 快照：commit_build_changes 与分支合并都可能移动 HEAD，
+          # 下游绑定/消息任务必须拿到「tag 这一刻」的 commit，而不是它们读取时的 HEAD
+          capture_git_commit_info
+
+          tag_result
         ensure
-          # 5. 还原 stash
+          # 6. 还原 stash
           restore_stash(root_dir, stash_name) if stash_saved
         end
       end

data/lib/pindo/module/task/model/git_task.rb

@@ -25,6 +25,9 @@ module Pindo
         @build_number = nil
         @commit_hash = nil
 
+        # commit 信息快照（由子类在 do_work 中调用 capture_git_commit_info 固化）
+        @git_commit_info = nil
+
         # 通过 project_path 获取 git_root_path
         @git_root_path = @project_path ? Pindo::GitHandler.git_root_directory(local_repo_dir: @project_path) : nil
 
@@ -91,6 +94,24 @@ module Pindo
         Pindo::GitHandler.git!(%W(-C #{@git_root_path} rev-parse --abbrev-ref HEAD)).strip
       end
 
+      # 固化当前 HEAD 的 commit 信息快照
+      #
+      # build_task_param 默认在被读取时才去读 HEAD，若期间有其它任务移动了 HEAD
+      # （例如 GitTagTask 会提交构建注入文件），不同时刻读到的 commit 就不一致。
+      # 子类在 do_work 中调用本方法，即可把「任务完成那一刻」的 commit 固定下来。
+      def capture_git_commit_info
+        return unless @git_root_path
+
+        # 传入任务自身的 tag 前缀，自定义 --tag_pre 时才能正确识别 HEAD 上的版本 tag
+        info = Pindo::GitHandler.get_latest_conventional_commit(
+          project_dir: @git_root_path,
+          tag_prefix: @tag_pre
+        )
+        @git_commit_info = info if info && info[:commit_id]
+      rescue => e
+        Funlog.instance.fancyinfo_warning("固化 git commit 信息失败: #{e.message}")
+      end
+
       # 构建任务参数（供其他任务使用）
       def build_task_param
         return {} unless @status == TaskStatus::SUCCESS
@@ -110,8 +131,12 @@ module Pindo
         # 添加 git commit 信息（供 JPSUploadMediaTask 等任务使用）
         if @git_root_path
           begin
-            # 获取当前 HEAD commit 信息
-            git_commit_info = Pindo::GitHandler.get_latest_conventional_commit(project_dir: @git_root_path)
+            # 优先使用任务内固化的快照；没有快照时回退到读取当前 HEAD
+            git_commit_info = @git_commit_info ||
+                              Pindo::GitHandler.get_latest_conventional_commit(
+                                project_dir: @git_root_path,
+                                tag_prefix: @tag_pre
+                              )
             if git_commit_info
               param[:git_commit_id] = git_commit_info[:commit_id]
               param[:git_commit_time] = git_commit_info[:commit_time]

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

@@ -27,8 +27,9 @@ module Pindo
       # @option options [String] :git_commit_time Git commit 时间（可选）
       # @option options [String] :git_commit_desc Git commit 描述（可选）
       # @option options [String] :project_dir 项目目录（可选，用于自动获取 commit 信息）
-      # @option options [Hash] :app_info_obj JPS 应用信息对象（可选，继承自基类）
-      # @option options [Hash] :workflow_info 工作流信息（可选，继承自基类）
+      # @option options [Hash] :app_info_obj JPS 应用信息对象（必需，用于取 project_id；
+      #   绑定与查询都以项目为作用域，不再依赖 workflow_info）
+      # @option options [Hash] :workflow_info 工作流信息（可选，继承自基类，本任务不使用）
       # @option options [String] :project_name 项目名称（可选，继承自基类）
       def initialize(app_version_list = nil, options = {})
         # 兼容性处理：如果传入的是单个 Hash，转为数组
@@ -48,6 +49,11 @@ module Pindo
         # 设置任务优先级为 LOW，确保在上传任务之后执行
         options[:priority] ||= TaskPriority::LOW
 
+        # 重试延迟加随机抖动：绑定是「读取 → 合并 → 覆盖」，两个进程冲突后若都按固定
+        # 延迟重试，会在同一时刻再次相撞。抖动只降低碰撞概率，消除不了竞态——
+        # 根治需要服务端提供原子追加或 CAS（见 do_work 里的说明）。
+        options[:retry_delay] ||= self.class.default_retry_delay + rand(0..4)
+
         super("绑定 包到Git工作流", options)
       end
 
@@ -136,18 +142,24 @@ module Pindo
           raise "无法登录 JPS，请检查配置"
         end
 
-        # 6. 获取工作流 ID
-        workflow_id = @workflow_info&.dig(:workflow_id) || @workflow_info&.dig('id')
-        unless workflow_id
-          raise "缺少 workflow_info，无法获取 workflow_id"
+        # 6. 获取项目 ID（绑定与查询都以项目为作用域）
+        project_id = @app_info_obj&.dig("id") || @app_info_obj&.dig(:id)
+        unless project_id
+          raise "缺少 app_info_obj，无法获取 project_id"
         end
 
         # 7. 获取当前 commit 已绑定的包 ID
         existing_bound_ids = pgyer_helper.get_commit_bound_package_ids(
           commit_id: @git_commit_id,
-          workflow_id: workflow_id
+          project_id: project_id
         )
 
+        # 查询失败（nil）时中止：绑定接口是覆盖式写入，带着不完整的列表提交
+        # 会把该 commit 上已绑定的其它平台包冲掉。宁可报错让用户重试或补绑。
+        if existing_bound_ids.nil?
+          raise "无法确认 Commit #{@git_commit_id[0..7]} 已绑定的包，为避免覆盖丢失已中止绑定，请重试"
+        end
+
         if existing_bound_ids.any?
           puts "  📋 当前 Commit 已绑定的包: #{existing_bound_ids.size} 个"
         end
@@ -172,6 +184,20 @@ module Pindo
 
         if bind_result[:success]
           Funlog.instance.fancyinfo_success("绑定成功！")
+
+          # 10. 写后回读校验
+          #
+          # 已知限制：「查询 → 合并 → 覆盖」跨进程不是原子的，客户端消除不了这个竞态。
+          # bind_commit 的入参只有 {commitId, projectPackageIds}，既没有 revision/CAS
+          # 也没有追加语义，同项目下的其它接口同样不提供（已核对全部 project_package/
+          # commit_log 接口）。因此本校验只能发现「本次写入的包在回读时不见了」，
+          # 发现不了「本次写入覆盖掉了别人刚加的包」——后者要等对方回读时才暴露。
+          #
+          # 根治需要服务端支持，二选一即可：
+          #   1) bind_commit 增加 append 语义（只追加不覆盖）
+          #   2) 返回并校验 revision，做乐观并发控制
+          verify_bound_packages(pgyer_helper, project_id, merged_package_ids)
+
           puts ""
 
           {
@@ -193,6 +219,35 @@ module Pindo
 
       private
 
+      # 写后回读校验：确认期望绑定的包都在服务端的绑定列表里
+      #
+      # 查询失败时只告警不失败——包已经写进去了，回读失败不代表绑定失败。
+      # 只有确认「期望的包没在列表里」才判定为被并发覆盖，抛异常交给任务重试。
+      #
+      # @param pgyer_helper [PgyerHelper] 已登录的 helper
+      # @param project_id [String] 项目 ID
+      # @param expected_ids [Array<String>] 本次写入的包 ID 列表
+      def verify_bound_packages(pgyer_helper, project_id, expected_ids)
+        actual_ids = pgyer_helper.get_commit_bound_package_ids(
+          commit_id: @git_commit_id,
+          project_id: project_id
+        )
+
+        if actual_ids.nil?
+          Funlog.instance.fancyinfo_warning("绑定后回读校验未能完成，请到 JPS 确认绑定结果")
+          return
+        end
+
+        missing_ids = expected_ids - actual_ids
+        return if missing_ids.empty?
+
+        # 抛出后由任务的重试机制重新走「查询 → 合并 → 写入」，对两种成因都收敛：
+        # 并发覆盖时会重新读到对方的包并一起写回；服务端写后读延迟时下一次读到的即是新值。
+        raise "绑定结果校验失败：#{missing_ids.size} 个包未出现在绑定列表中" \
+              "（其它进程同时绑定覆盖了本次结果，或服务端写入尚未可见），" \
+              "缺失包 ID: #{missing_ids.join(', ')}"
+      end
+
       # 从依赖任务获取 app_version_list
       def fetch_app_version_from_dependencies
         # 获取所有 JPSUploadTask 的数据（可能有多个平台的上传任务）
@@ -210,10 +265,8 @@ module Pindo
 
       # 从依赖任务获取或自动获取 git commit 信息
       def fetch_git_commit_info
-        # 1. 优先从 GitTagTask 依赖任务获取（打 tag 后的 commit 信息更准确）
-        git_data = get_data_param_by_key(:git_tag)
-        # 2. 降级到 GitCommitTask
-        git_data = get_data_param_by_key(:git_commit) if git_data.nil? || git_data.empty?
+        # 1. 从依赖任务获取（优先 GitTagTask，降级 GitCommitTask）
+        git_data = git_commit_data_param
 
         if git_data && git_data[:task_param]
           param = git_data[:task_param]
@@ -222,7 +275,7 @@ module Pindo
           @git_commit_desc = param[:git_commit_desc] if param[:git_commit_desc]
         end
 
-        # 3. 如果依赖任务都没有提供，且指定了 project_dir，使用自动获取
+        # 2. 如果依赖任务都没有提供，且指定了 project_dir，使用自动获取
         if (@git_commit_id.nil? || @git_commit_id.empty?) && @project_dir
           # 查找 git 仓库根目录
           git_root = Pindo::GitHandler.git_root_directory(local_repo_dir: @project_dir)

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

@@ -33,12 +33,16 @@ module Pindo
       # @option options [Hash] :app_info_obj JPS 应用信息对象（可选，继承自基类）
       # @option options [Hash] :workflow_info 工作流信息（可选，继承自基类）
       # @option options [String] :project_name 项目名称（可选，继承自基类）
+      # @option options [Boolean] :required 用户是否显式要求上传媒体（默认 false）。
+      #   为 true 时找不到媒体文件会让任务失败；--bind/--send 隐式带出的媒体上传保持
+      #   宽松，因为「项目里没有 JPSMedia 文件」是常态，不该让整条构建失败。
       def initialize(file_paths, upload_path, options = {})
         @file_paths = file_paths || []                  # 要上传的文件路径列表
         @upload_path = upload_path                      # 项目路径
         @git_commit_id = options[:git_commit_id]        # Git commit SHA
         @git_commit_time = options[:git_commit_time]    # Git commit 时间
         @git_commit_desc = options[:git_commit_desc]    # Git commit 描述
+        @required = options.fetch(:required, false)     # 是否为用户显式要求
 
         # 设置任务优先级为 LOW，确保在其他任务之后执行
         options[:priority] ||= TaskPriority::LOW
@@ -97,10 +101,8 @@ module Pindo
 
         # 2. 如果没有提供 git_commit_id，尝试从依赖任务获取或自动获取
         if @git_commit_id.nil? || @git_commit_id.empty?
-          # 2.1 优先从 GitTagTask 依赖任务获取（打 tag 后的 commit 信息更准确）
-          git_data = get_data_param_by_key(:git_tag)
-          # 2.2 降级到 GitCommitTask
-          git_data = get_data_param_by_key(:git_commit) if git_data.nil? || git_data.empty?
+          # 2.1 从依赖任务获取（优先 GitTagTask，降级 GitCommitTask）
+          git_data = git_commit_data_param
 
           if git_data && git_data[:task_param]
             param = git_data[:task_param]
@@ -110,7 +112,7 @@ module Pindo
             @git_commit_desc = param[:git_commit_desc] if param[:git_commit_desc]
           end
 
-          # 2.3 如果依赖任务都没有提供，使用 get_latest_conventional_commit
+          # 2.2 如果依赖任务都没有提供，回退到读取当前仓库状态
           if @git_commit_id.nil? || @git_commit_id.empty?
             git_info = Pindo::GitHandler.get_latest_conventional_commit(project_dir: git_root)
             @git_commit_id = git_info[:commit_id]
@@ -154,6 +156,13 @@ module Pindo
           puts "  ❌ 没有找到有效的 media 文件"
           puts "  提示: 请在项目根目录创建 JPSMedia/ 目录并放入要上传的图片或视频文件"
           puts ""
+
+          # 用户显式传了 --media 却没有文件可传：任务系统只看异常不看 result[:success]，
+          # 这里不抛出的话命令会以 0 退出，等于悄悄没做用户要求的事
+          if @required
+            raise "没有找到有效的 media 文件；请在 JPSMedia/ 目录放入图片或视频后重试"
+          end
+
           return {
             success: false,
             success_urls: [],

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

@@ -27,7 +27,7 @@ module Pindo
       # @option options [String] :git_commit_desc Git commit 描述（可选）
       # @option options [String] :project_id 项目 ID（可选，从 app_info_obj 获取）
       # @option options [Integer] :workflow_id 工作流 ID（可选，从 workflow_info 获取）
-      # @option options [String] :branch 分支名（可选，默认 'master'）
+      # @option options [String] :branch 分支名（可选，默认从依赖的 Git 任务取实际发布分支）
       # @option options [Boolean] :single 是否单个提交（默认 true）
       # @option options [Hash] :app_info_obj JPS 应用信息对象（可选，用于获取 project_id）
       # @option options [Hash] :workflow_info 工作流信息（可选，用于获取 workflow_id）
@@ -37,7 +37,9 @@ module Pindo
         @git_commit_desc = options[:git_commit_desc]
         @project_id = options[:project_id]
         @workflow_id = options[:workflow_id]
-        @branch = options[:branch] || 'master'
+        # 不在这里兜底成 master：仓库主干可能是 main 或其它分支，
+        # 未显式指定时统一从依赖的 Git 任务取 resolve 之后的真实发布分支
+        @branch = options[:branch]
         @single = options.fetch(:single, true)
 
         # 消息发送任务优先级为 LOW，确保在其他任务之后执行
@@ -63,7 +65,10 @@ module Pindo
           # 2. 验证必需参数
           validate_required_params!
 
-          # 3. 发送消息
+          # 3. 确定分支（取不到则不带分支发送）
+          resolve_branch!
+
+          # 4. 发送消息
           send_workflow_message
 
           puts "  ✅ JPS 工作流消息发送完成\n"
@@ -86,23 +91,24 @@ module Pindo
 
       # 判断是否需要从依赖任务获取数据
       def need_fetch_dependencies?
-        @git_commit_id.nil? || @project_id.nil? || @workflow_id.nil?
+        @git_commit_id.nil? || @project_id.nil? || @workflow_id.nil? || @branch.nil?
       end
 
       # 从依赖任务获取数据
       def fetch_data_from_dependencies
-        # 1. 获取 commit 信息（优先从 GitTagTask，降级到 GitCommitTask）
-        if @git_commit_id.nil?
-          # 1.1 优先从 GitTagTask 依赖任务获取（打 tag 后的 commit 信息更准确）
-          git_data = get_data_param_by_key(:git_tag)
-          # 1.2 降级到 GitCommitTask
-          git_data = get_data_param_by_key(:git_commit) if git_data.nil? || git_data.empty?
+        # 1. 获取 commit 信息与发布分支（优先从 GitTagTask，降级到 GitCommitTask）
+        if @git_commit_id.nil? || @branch.nil?
+          git_data = git_commit_data_param
 
           if git_data && git_data[:task_param]
             param = git_data[:task_param]
-            @git_commit_id = param[:git_commit_id] if param[:git_commit_id]
-            @git_commit_time = param[:git_commit_time] if param[:git_commit_time]
-            @git_commit_desc = param[:git_commit_desc] if param[:git_commit_desc]
+            # 一律只在调用方没给值时才填充，避免显式传入的 commit 信息被依赖任务覆盖
+            @git_commit_id = param[:git_commit_id] if @git_commit_id.nil? && param[:git_commit_id]
+            @git_commit_time = param[:git_commit_time] if @git_commit_time.nil? && param[:git_commit_time]
+            @git_commit_desc = param[:git_commit_desc] if @git_commit_desc.nil? && param[:git_commit_desc]
+            # release_branch 是 GitCommitTask/GitTagTask 用 resolve_release_branch
+            # 探测出来的真实分支（master > main > 唯一远程分支 > 当前分支）
+            @branch = param[:release_branch] if @branch.nil? && param[:release_branch]
           end
         end
 
@@ -152,13 +158,25 @@ module Pindo
         end
       end
 
+      # 确定要发送的分支
+      #
+      # 取不到时保持 nil 而不是兜底成 master：branches 在服务端是可选字段，不传即可，
+      # 但传一个错的分支名（detached HEAD、无 Git 依赖等场景）会让 commit 与分支
+      # 错误关联，比不传更糟。
+      def resolve_branch!
+        return unless @branch.to_s.strip.empty?
+
+        @branch = nil
+        Funlog.instance.fancyinfo_warning("未取到当前分支，工作流消息将不带分支信息发送")
+      end
+
       # 发送工作流消息
       def send_workflow_message
         puts "  📨 发送工作流消息..."
         puts "     Project ID: #{@project_id}"
         puts "     Workflow ID: #{@workflow_id}"
         puts "     Commit ID: #{@git_commit_id[0..7]}" if @git_commit_id
-        puts "     Branch: #{@branch}"
+        puts "     Branch: #{@branch || '(不指定)'}"
         puts ""
 
         pgyer_helper = PgyerHelper.share_instace