Class: BBItools::DocCGenerator

Inherits:

Object

• Object
• BBItools::DocCGenerator

Defined in:

lib/cocoapods-bb-PodAssistant/tools/docc_generator.rb

Constant Summary

PODSPEC_REPO =

"babybus-babybus-ios-specs-babybus-specs"

DESTINATION =

"generic/platform=iOS Simulator"

CONFIGURATION =

"Debug"

KEYCHAIN_HOST =

"git.babybus.co"

Class Method Summary

• .generate(options) ⇒ Object

Instance Method Summary

• #initialize(options) ⇒ DocCGenerator constructor

  A new instance of DocCGenerator.

• #run ⇒ Object

Constructor Details

#initialize(options) ⇒ DocCGenerator

Returns a new instance of DocCGenerator.

# File 'lib/cocoapods-bb-PodAssistant/tools/docc_generator.rb', line 22

def initialize(options)
  @options = options
  @podspec = options[:podspec]
  @workdir = options[:workdir]
  @output = options[:output]
  @logs = options[:logs]
  @derived_data = options[:derived_data]
  @lint_root = options[:lint_root]
  @hosting_base_path = options[:hosting_base_path]
  @subspec = options[:subspec]
end

Class Method Details

.generate(options) ⇒ Object

# File 'lib/cocoapods-bb-PodAssistant/tools/docc_generator.rb', line 13

def self.generate(options)
  new(options).run
rescue SystemExit => e
  e.status.to_i
rescue StandardError => e
  warn "[docc][error] #{e.class}: #{e.message}"
  1
end

Instance Method Details

#run ⇒ Object

# File 'lib/cocoapods-bb-PodAssistant/tools/docc_generator.rb', line 34

def run
  $stdout.sync = true
  $stderr.sync = true

  fail!("必须传入 podspec") if @podspec.to_s.strip.empty?

  base_dir = Dir.pwd
  podspec_path_abs = abs_path(@podspec.to_s.strip, base_dir: base_dir)
  fail!("podspec 不存在: #{@podspec}") unless File.file?(podspec_path_abs)
  
  # ---------------------------------------------------------
  # 0. Subspec 自动拆分逻辑
  # ---------------------------------------------------------
  should_split = ENV["BB_DOCC_SPLIT_SUBSPECS"] != "0"
  log "🔍 检查 Subspec 拆分 (should_split=#{should_split}, subspec=#{@subspec}, podspec=#{podspec_path_abs})"
  
  if should_split && @subspec.nil?
    subspec_short_names = nil

    # 仅捕获 Subspec 列表解析阶段的异常；子任务生成异常应直接抛出，便于定位真实失败点
    begin
      require "cocoapods"
      spec = Pod::Spec.from_file(podspec_path_abs)
      subspecs = spec.subspecs.reject { |s| s.test_specification? || s.app_specification? }
      subspec_short_names = subspecs.map(&:name).map { |n| n.include?("/") ? n.split("/").last : n }.uniq
    rescue LoadError
      log "⚠️ 无法加载 CocoaPods 库，跳过 Subspec 检测"
      subspec_short_names = nil
    rescue StandardError => e
      log "⚠️ Subspec 列表解析失败: #{e.message}"
      log e.backtrace.join("\n")
      subspec_short_names = nil
    end

    if subspec_short_names && subspec_short_names.any?
      log "检测到 Subspecs (#{subspec_short_names.count}个): #{subspec_short_names.join(', ')}"
      results = subspec_short_names.map do |subspec_short_name|
        log "➡️ 开始递归处理 Subspec: #{subspec_short_name}"
        BBItools::DocCGenerator.generate(@options.merge(subspec: subspec_short_name, hosting_base_path: nil)).to_i
      end
      failed = results.count { |c| c != 0 }
      log "✅ 所有 Subspecs 处理完毕 (failed=#{failed}/#{results.size})"
      return failed.zero? ? 0 : 1
    end
  end

  # ---------------------------------------------------------
  # 1. 初始化变量与环境
  # ---------------------------------------------------------
  podspec_path_rel = rel_path(podspec_path_abs, base_dir: base_dir)
  podspec_basename = File.basename(podspec_path_abs)
  workdir_opt = @workdir.to_s.strip
  podspec_dir_abs =
    if workdir_opt.empty?
      File.dirname(podspec_path_abs)
    else
      abs_path(workdir_opt, base_dir: base_dir)
    end
  fail!("workdir 不存在: #{rel_path(podspec_dir_abs, base_dir: base_dir)}") unless File.directory?(podspec_dir_abs)
  
  # 如果指定了 workdir，且 podspec 不在其中，则复制过去
  podspec_in_workdir = File.join(podspec_dir_abs, podspec_basename)
  if File.expand_path(podspec_in_workdir) != File.expand_path(podspec_path_abs)
    FileUtils.cp(podspec_path_abs, podspec_in_workdir)
  end

  zip_push_repo = ENV["BB_DOCC_ZIP_PUSH_REPO"].to_s.strip
  zip_push_repo = "https://git.babybus.co/babybus/ios/CommonBusiness/Tools/iOSWeb" if zip_push_repo.empty?
  zip_push_branch = ENV["BB_DOCC_ZIP_PUSH_BRANCH"].to_s.strip
  zip_push_branch = "main" if zip_push_branch.empty?
  zip_push_subdir = ENV["BB_DOCC_ZIP_PUSH_SUBDIR"].to_s.strip
  zip_push_subdir = "docc_zips" if zip_push_subdir.empty?

  final_destination_root = nil
  real_home = ENV["HOME"].to_s
  
  # 获取 Pod 名称 (Scheme)
  scheme = extract_name_from_podspec(podspec_path_abs)
  spec_version = extract_version_from_podspec(podspec_path_abs)
  default_subspec = extract_default_subspec_from_podspec(podspec_path_abs)
  deployment_target = extract_ios_deployment_target_from_podspec(podspec_path_abs)
  
  # 确定组件名称 (用于目录名、hosting path 等)
  # 如果是 Subspec，组件名为 Scheme_Subspec
  component_name = @subspec ? "#{scheme}_#{@subspec}" : scheme
  
  # ---------------------------------------------------------
  # 2. 所有操作都在脚本同级目录下的 _docc_temp/component_name 中进行
  # ---------------------------------------------------------
  local_work_root = File.join(Dir.pwd, "_docc_temp", component_name)
  FileUtils.rm_rf(local_work_root) # 清理旧的
  FileUtils.mkdir_p(local_work_root)
  
  log "🔨 本地工作区 (生成中): file://#{local_work_root}"

  # 各个子目录都在本地工作区内
  logs_dir = File.join(local_work_root, "logs")
  FileUtils.mkdir_p(logs_dir)
  
  derived_data_root = File.join(local_work_root, "DerivedData")
  FileUtils.mkdir_p(derived_data_root)
  
  lint_root = File.join(local_work_root, "Lint")
  FileUtils.mkdir_p(lint_root)
  lint_root_rel = lint_root

  # 最终生成的站点先放在本地
  local_site_output = File.join(local_work_root, "site_output")
  FileUtils.mkdir_p(local_site_output)

  # 模拟 component_dir_abs 供后续逻辑使用 (指向本地)
  component_dir_abs = local_site_output
  component_dir_rel = component_dir_abs

  # 确定 Hosting Base Path
  hosting_base_path = @options[:hosting_base_path].to_s.strip
  if hosting_base_path.empty?
    # 默认与线上目录结构保持一致：/Docs/<组件名>/
    hosting_base_path = "Docs/#{component_name}"
  end

  # 确保 hosting_base_path 以 / 开头 (DocC 要求)
  hosting_base_path = "/#{hosting_base_path}" unless hosting_base_path.start_with?("/")

  status_md = File.join(logs_dir, "status.md")
  File.open(status_md, "w") do |f|
    f.puts "# #{component_name}"
    f.puts
    f.puts "- 时间: #{Time.now.strftime("%Y-%m-%d %H:%M:%S")}"
    f.puts "- podspec: #{podspec_path_rel}"
    f.puts "- version: #{spec_version}" unless spec_version.to_s.strip.empty?
    f.puts "- default_subspec: #{default_subspec}" unless default_subspec.to_s.strip.empty?
    f.puts "- subspec: #{@subspec}" if @subspec
    f.puts "- workdir: #{rel_path(podspec_dir_abs, base_dir: base_dir)}" unless workdir_opt.empty?
    f.puts "- local_work_root: #{local_work_root}"
    f.puts "- zip_push_repo: #{redact_git_url(zip_push_repo)}"
    f.puts "- zip_push_branch: #{zip_push_branch}"
    f.puts "- zip_push_subdir: #{zip_push_subdir}"
    f.puts "- home: ~"
    f.puts "- deployment_target: #{deployment_target}" unless deployment_target.to_s.strip.empty?
    f.puts "- hosting_base_path: #{hosting_base_path}"
    f.puts "- sources: #{PODSPEC_REPO}"
  end

  exported_source_root = File.join(component_dir_abs, "exported-source")
  export_staging_dir = ""
  cleanup_written = false
  is_success = false

  # Cleanup hook
  at_exit_block = proc do
    next if cleanup_written
    cleanup_written = true

    exit_code = $!.is_a?(SystemExit) ? $!.status : 0
    
    # ---------------------------------------------------------
    # 3. 任务结束：移动产物到 SMB 并清理本地 (保留原有逻辑结构)
    # ---------------------------------------------------------
    if final_destination_root
       # (此段保持原有逻辑，主要是针对 SMB 部署，这里省略具体修改，保持原样)
       # ...
    end

    # 强制删除本地临时目录 (_docc_temp/component_name)
    # 只有在完全成功且不需要调试时才删除，或者保留？
    # 为了调试方便，暂时不自动删除根目录，由外部控制
  end

  begin
    require_cmd!("pod")
    require_cmd!("xcodebuild")
    require_cmd!("xcrun")
    require_cmd!("git")

    # ---------------------------------------------------------
    # 4. 执行 Pod Lib Lint
    # ---------------------------------------------------------
    lint_log = File.join(logs_dir, "pod-lib-lint.log")
    lint_log_rel = rel_path(lint_log, base_dir: base_dir)
    lint_cmd = [
      "pod", "lib", "lint", podspec_basename,
      "--verbose", "--no-clean", "--skip-tests", "--skip-import-validation",
      "--use-modular-headers", "--use-static-frameworks",
      "--allow-warnings",
      "--sources=#{PODSPEC_REPO}"
    ]
    
    # 如果指定了 subspec，添加到 lint 命令
    lint_cmd << "--subspec=#{@subspec}" if @subspec

    File.open(status_md, "a") { |f| f.puts "- lint: #{lint_cmd.join(" ")}" }

    log "执行 lint: #{podspec_basename}#{ @subspec ? " (subspec: #{@subspec})" : "" }（cwd=#{rel_path(podspec_dir_abs, base_dir: base_dir)}）"
    lint_env = {
      "HOME" => real_home,
      "TMPDIR" => lint_root
    }

    if ENV["BB_DOCC_ALLOW_PROMPT"] != "1"
      lint_env["GIT_TERMINAL_PROMPT"] = "0"
    end

    lint_exit = run_to_file(lint_cmd, cwd: podspec_dir_abs, env: lint_env, log_path: lint_log)

    File.open(status_md, "a") do |f|
      if lint_exit.zero?
        f.puts "- lint: 成功"
      else
        f.puts "- lint: 失败（exit=#{lint_exit}）"
      end
      f.puts
      f.puts "**pod lib lint 日志（尾部）**"
      f.puts "```"
      tail_lines(lint_log, 200).each { |line| f.puts line }
      f.puts "```"
    end

    # ---------------------------------------------------------
    # 5. Lint 失败处理 (软失败)
    # ---------------------------------------------------------
    unless lint_exit.zero?
      log "⚠️ Lint 失败 (exit=#{lint_exit})，尝试继续执行 docbuild..."
      log "失败日志: #{lint_log_rel}"
      
      # 打印关键错误信息
      puts "[docc] -------- pod lib lint 日志（尾部 200 行）--------"
      puts tail_lines(lint_log, 200).join("\n")
      
      # 检查是否是 Git 认证问题
      if safe_read_text(lint_log).include?("Authentication failed for 'https://#{KEYCHAIN_HOST}/")
        puts "[docc] 提示: 检测到 git clone 认证失败（#{KEYCHAIN_HOST}）"
      end
      
      # 注意：这里不 return，继续尝试寻找 workspace
    end

    # ---------------------------------------------------------
    # 6. 查找 Workspace 并执行 DocBuild
    # ---------------------------------------------------------
    workspace_path_abs = find_workspace_from_lint_log(lint_log, lint_root)
    
    if workspace_path_abs.to_s.strip.empty?
      fail!("未找到 *.xcworkspace（lint_root=#{lint_root_rel}），无法继续")
    end
    
    workspace_path_rel = rel_path(workspace_path_abs.to_s, base_dir: base_dir)
    fail!("workspace 不存在: #{workspace_path_rel}") unless File.directory?(workspace_path_abs)

    validation_dir_abs = File.dirname(workspace_path_abs)
    File.open(status_md, "a") do |f|
      f.puts "- validation_dir: #{rel_path(validation_dir_abs, base_dir: base_dir)}"
      f.puts "- workspace: #{workspace_path_rel}"
    end

    if deployment_target && !deployment_target.strip.empty?
      changed = bump_deployment_targets_in_validation_dir(validation_dir_abs, deployment_target)
      File.open(status_md, "a") { |f| f.puts "- bumped_deployment_target: #{deployment_target} (changed=#{changed})" }
    end

    exported_source = ""
    # 尝试查找源码目录 (通常在 Development Pods 下)
    # 注意：如果是 Subspec，目录结构可能不同，但 Scheme 应该还是主 Pod 名
    dev_pod_dir = File.join(validation_dir_abs, "Pods", "Development Pods", scheme)
    if File.directory?(dev_pod_dir)
      FileUtils.rm_rf(exported_source_root)
      FileUtils.mkdir_p(exported_source_root)
      FileUtils.cp_r(dev_pod_dir, exported_source_root)
      exported_source = File.join(exported_source_root, scheme)
    end

    File.open(status_md, "a") do |f|
      if exported_source.empty?
        f.puts "- exported_source: 未找到（跳过）"
      else
        f.puts "- exported_source: #{rel_path(exported_source, base_dir: base_dir)}"
      end
    end

    derived_dir = File.join(derived_data_root, scheme)
    FileUtils.mkdir_p(derived_dir)
    derived_dir_rel = rel_path(derived_dir, base_dir: base_dir)

    docbuild_log = File.join(logs_dir, "xcodebuild-docbuild.log")

    workspace_for_docbuild = rel_path(workspace_path_abs, base_dir: podspec_dir_abs)
    derived_dir_for_docbuild = rel_path(derived_dir, base_dir: podspec_dir_abs)
    
    # DocBuild Command
    docbuild_cmd = [
      "xcodebuild", "docbuild",
      "-workspace", workspace_for_docbuild,
      "-scheme", scheme, # 通常 Subspec 的 Scheme 还是主 Pod 名
      "-destination", DESTINATION,
      "-configuration", CONFIGURATION,
      "-derivedDataPath", derived_dir_for_docbuild,
      "ENABLE_USER_SCRIPT_SANDBOXING=NO" # 尝试解决 Swift Macro 权限问题
    ]

    docc_catalog_abs = resolve_docc_catalog_abs(podspec_dir_abs, scheme)
    if docc_catalog_abs
      docc_catalog_rel_for_status = rel_path(docc_catalog_abs, base_dir: podspec_dir_abs)
      from_sources = path_inside_dir?(docc_catalog_abs, File.join(podspec_dir_abs, "Sources"))
      File.open(status_md, "a") do |f|
        f.puts "- docc_catalog: #{docc_catalog_rel_for_status}"
        if from_sources
          f.puts "- docc_catalog_source: sources(auto, 未依赖 podspec DOCC_CATALOGS)"
        else
          f.puts "- docc_catalog_source: root(auto)"
        end
      end
      docbuild_cmd << "DOCC_CATALOGS=#{docc_catalog_abs}"
    else
      File.open(status_md, "a") { |f| f.puts "- docc_catalog: 未找到（将使用工程默认配置）" }
    end

    if deployment_target && !deployment_target.strip.empty?
      docbuild_cmd << "IPHONEOS_DEPLOYMENT_TARGET=#{deployment_target}"
      docbuild_cmd << "SWIFT_VERSION=5.0"
    end
    docbuild_cmd += ["CODE_SIGNING_ALLOWED=NO", "CODE_SIGNING_REQUIRED=NO", "CODE_SIGN_IDENTITY="]

    docbuild_cmd_report = docbuild_cmd.dup
    docbuild_cmd_report[docbuild_cmd_report.index(workspace_for_docbuild) || 0] = workspace_path_rel
    docbuild_cmd_report[docbuild_cmd_report.index(derived_dir_for_docbuild) || 0] = derived_dir_rel
    File.open(status_md, "a") { |f| f.puts "- docbuild: #{docbuild_cmd_report.join(" ")}" }

    log "执行 docbuild: #{scheme} (target: #{component_name})"
    docbuild_exit = run_to_file(docbuild_cmd, cwd: podspec_dir_abs, env: { "HOME" => real_home }, log_path: docbuild_log)

    unless docbuild_exit.zero?
      File.open(status_md, "a") do |f|
        f.puts "- docbuild: 失败（exit=#{docbuild_exit}）"
        f.puts
        f.puts "**xcodebuild 日志（尾部）**"
        f.puts "```"
        tail_lines(docbuild_log, 200).each { |line| f.puts line }
        f.puts "```"
      end
      fail!("docbuild 失败")
    end

    File.open(status_md, "a") { |f| f.puts "- docbuild: 成功" }

    archives = []
    Find.find(derived_dir) do |p|
      next unless File.directory?(p)
      next unless p.end_with?(".doccarchive")
      archives << p
      Find.prune
    end

    doccarchive_path =
      archives
        .select { |p| File.directory?(p) }
        .sort_by { |p| File.mtime(p) }
        .reverse
        .find { |p| File.basename(p) == "#{scheme}.doccarchive" } || archives.max_by { |p| File.mtime(p) }

    fail!("未找到 .doccarchive（derivedData=#{derived_dir_rel}）") if doccarchive_path.to_s.strip.empty?

    want_tutorials = false
    if docc_catalog_abs && File.directory?(docc_catalog_abs)
      has_tutorial = Dir.glob(File.join(docc_catalog_abs, "**", "*.tutorial")).any?
      want_tutorials = has_tutorial
    end

    if want_tutorials
      has_in_archive = File.directory?(File.join(doccarchive_path, "tutorials")) || File.directory?(File.join(doccarchive_path, "data", "tutorials"))
      unless has_in_archive
        symbol_graph_dir = Dir.glob(File.join(derived_dir, "Build", "Intermediates.noindex", "**", "#{scheme}.build", "symbol-graph")).sort.first
        fail!("未找到 symbol-graph 目录，无法按官方 docc convert 生成教程") if symbol_graph_dir.to_s.strip.empty?

        manual_archive_dir = File.join(derived_data_root, ".manual_doccarchive", component_name, "#{scheme}.doccarchive")
        FileUtils.rm_rf(manual_archive_dir)
        FileUtils.mkdir_p(File.dirname(manual_archive_dir))

        manual_log = File.join(logs_dir, "docc-convert-manual.log")
        manual_diag = File.join(logs_dir, "docc-convert-manual-diagnostics.json")

        manual_cmd = [
          "xcrun", "docc", "convert", docc_catalog_abs,
          "--emit-lmdb-index",
          "--fallback-display-name", scheme,
          "--fallback-bundle-identifier", "org.cocoapods.#{scheme}",
          "--output-dir", manual_archive_dir,
          "--additional-symbol-graph-dir", symbol_graph_dir,
          "--ide-console-output",
          "--diagnostics-file", manual_diag
        ]

        manual_exit = run_to_file(manual_cmd, cwd: podspec_dir_abs, env: { "HOME" => real_home }, log_path: manual_log)
        fail!("docc convert 失败（exit=#{manual_exit}）") unless manual_exit.zero? && File.directory?(manual_archive_dir)

        doccarchive_path = manual_archive_dir
      end
    end

    doccarchive_rel = rel_path(doccarchive_path, base_dir: base_dir)
    File.open(status_md, "a") { |f| f.puts "- doccarchive: #{doccarchive_rel}" }

    site_out = component_dir_abs
    FileUtils.mkdir_p(site_out)

    export_log = File.join(logs_dir, "docc-transform.log")

    doccarchive_for_export = rel_path(doccarchive_path, base_dir: podspec_dir_abs)
    export_staging_dir = File.join(derived_data_root, ".docc-site", scheme)
    FileUtils.rm_rf(export_staging_dir)
    FileUtils.mkdir_p(export_staging_dir)
    site_out_for_export = rel_path(export_staging_dir, base_dir: podspec_dir_abs)
    
    # Export Command
    export_cmd = [
      "xcrun", "docc", "process-archive", "transform-for-static-hosting",
      doccarchive_for_export,
      "--output-path", site_out_for_export,
      "--hosting-base-path", hosting_base_path # 关键参数
    ]

    export_cmd_report = export_cmd.dup
    export_cmd_report[export_cmd_report.index(doccarchive_for_export) || 0] = doccarchive_rel
    export_cmd_report[export_cmd_report.index(site_out_for_export) || 0] = rel_path(site_out, base_dir: base_dir)
    File.open(status_md, "a") { |f| f.puts "- export: #{export_cmd_report.join(" ")}" }

    log "导出静态站点: #{component_dir_rel} (hosting-base-path: #{hosting_base_path})"
    docc_html_dir = ENV["BB_DOCC_HTML_DIR"].to_s.strip
    docc_html_dir = ENV["DOCC_HTML_DIR"].to_s.strip if docc_html_dir.empty?

    if !docc_html_dir.empty? && !File.directory?(docc_html_dir)
      log "⚠️ DOCC_HTML_DIR 无效（目录不存在）：#{docc_html_dir}，将回退使用系统内置 DocC-Render"
      docc_html_dir = ""
    end

    export_env = { "HOME" => real_home }
    export_env["DOCC_HTML_DIR"] = docc_html_dir unless docc_html_dir.empty?

    File.open(status_md, "a") { |f| f.puts "- docc_html_dir: #{docc_html_dir.empty? ? '(builtin)' : docc_html_dir}" }

    export_exit = run_to_file(export_cmd, cwd: podspec_dir_abs, env: export_env, log_path: export_log)
    unless export_exit.zero?
      warn tail_lines(export_log, 200).join("\n")
      fail!("docc 导出失败")
    end

    sync_dir_contents(export_staging_dir, site_out)

    log "本地生成完成: file://#{component_dir_abs.gsub(' ', '%20')}"
    is_success = true

    # ---------------------------------------------------------
    # 8. 打包 Zip（站点文件平铺到 zip 根目录，避免线上解压后多一层目录导致 404）
    # ---------------------------------------------------------
    staging_dir = File.join(local_work_root, component_name)
    FileUtils.rm_rf(staging_dir)
    FileUtils.mv(local_site_output, staging_dir)

    # Zip 文件名为 component_name_<timestamp>_v<version>.zip
    ts = Time.now.strftime("%Y%m%d-%H%M%S")
    v_suffix = spec_version.to_s.strip.empty? ? "" : "_v#{spec_version}"
    zip_name = "#{component_name}_#{ts}#{v_suffix}.zip"
    local_zip_path = File.join(local_work_root, zip_name)

    zip_log = File.join(logs_dir, "zip.log")
    zip_timeout_sec = (ENV["BB_DOCC_ZIP_TIMEOUT_SEC"].to_s.strip.empty? ? 1800 : ENV["BB_DOCC_ZIP_TIMEOUT_SEC"].to_i)

    log "📦 正在压缩产物 (zip)... (timeout=#{zip_timeout_sec}s)"
    log "📄 zip 日志: #{rel_path(zip_log, base_dir: base_dir)}"

    zip_exit = nil
    FileUtils.mkdir_p(File.dirname(zip_log))
    File.open(zip_log, "w") do |f|
      Dir.chdir(staging_dir) do
        pid = Process.spawn({ "HOME" => real_home }, "zip", "-r", "-q", local_zip_path, ".", out: f, err: f)
        begin
          Timeout.timeout(zip_timeout_sec) do
            _pid, status = Process.wait2(pid)
            zip_exit = status.exitstatus
          end
        rescue Timeout::Error
          begin
            Process.kill("TERM", pid)
          rescue StandardError
          end
          sleep 2
          begin
            Process.kill("KILL", pid)
          rescue StandardError
          end
          zip_exit = 124
        end
      end
    end

    log "📦 压缩结束 (exit=#{zip_exit})"
    fail!("压缩失败，未找到 zip 文件") unless zip_exit == 0 && File.exist?(local_zip_path)
    
     # 9. 推送 Zip 到 Git (如果需要)
     skip_git_push = ENV["BB_DOCC_SKIP_GIT_PUSH"].to_s.strip == "1"
     if skip_git_push
       File.open(status_md, "a") { |f| f.puts "- git_push: skipped" }
       log "⚠️ Git 推送已跳过 (BB_DOCC_SKIP_GIT_PUSH=1)"
     else
       zip_rel_path_in_repo = File.join(zip_push_subdir, scheme, component_name, zip_name)

       git_log = File.join(logs_dir, "git-push.log")
       git_timeout_sec = (ENV["BB_DOCC_GIT_TIMEOUT_SEC"].to_s.strip.empty? ? 600 : ENV["BB_DOCC_GIT_TIMEOUT_SEC"].to_i)

       git_env = { "HOME" => real_home }
       git_env["GIT_TERMINAL_PROMPT"] = "0" if ENV["BB_DOCC_ALLOW_PROMPT"].to_s.strip != "1"

       log "🚚 正在推送 zip 到 Git: #{redact_git_url(zip_push_repo)} (branch=#{zip_push_branch})"
       log "📄 git 日志: #{rel_path(git_log, base_dir: base_dir)}"

       git_exit = push_zip_to_git(
         repo_url: zip_push_repo,
         branch: zip_push_branch,
         scheme: scheme, # Commit message 用
         zip_path: local_zip_path,
         zip_rel_path_in_repo: zip_rel_path_in_repo,
         log_path: git_log,
         env: git_env,
         timeout_sec: git_timeout_sec
       )

       File.open(status_md, "a") do |f|
         f.puts "- git_push: #{git_exit.zero? ? 'success' : "failed(exit=#{git_exit})"}"
       end

       fail!("推送 zip 失败（exit=#{git_exit}）") unless git_exit.zero?
       log "✅ Git 推送完成"
     end

     0

  ensure
    at_exit_block.call
  end
end