✨ feat(core): 优化 Homebrew 缓存清理策略

* 禁用安装步骤中的自动清理，统一在升级流程结束后执行
* 清理 Homebrew prefix 失效链接及日期早于今天的缓存
* 保留当天生成的下载缓存，并支持失败后继续清理
* 扩展全量清理参数支持并更新相关文档说明

homebrew/brew-upgrade-manager.sh

@@ -16,6 +16,9 @@ prepend_path_once "/usr/local/sbin"
 prepend_path_once "/opt/homebrew/sbin"
 export PATH
 
+# 禁止 Homebrew 在每个安装步骤后自动清理；统一在最后一步按缓存年龄清理。
+export HOMEBREW_NO_INSTALL_CLEANUP=1
+
 if [[ -t 1 ]]; then
     GREEN='\033[1;32m'
     YELLOW='\033[1;33m'
@@ -33,6 +36,7 @@ fi
 
 TERMINAL_WIDTH=""
 ACTIVE_LOG_FILE=""
+ACTIVE_CLEANUP_MARKER=""
 LOCK_ACQUIRED=0
 LOCK_DIR="${HB_LOCK_DIR:-${TMPDIR:-/tmp}/brewup-$(id -u).lock}"
 FAILED_FORMULAE=()
@@ -113,6 +117,9 @@ cleanup_runtime() {
     if [[ -n "${ACTIVE_LOG_FILE:-}" && -f "$ACTIVE_LOG_FILE" ]]; then
         rm -f "$ACTIVE_LOG_FILE"
     fi
+    if [[ -n "${ACTIVE_CLEANUP_MARKER:-}" && -f "$ACTIVE_CLEANUP_MARKER" ]]; then
+        rm -f "$ACTIVE_CLEANUP_MARKER"
+    fi
     if ((LOCK_ACQUIRED)); then
         rm -f "$LOCK_DIR/pid"
         rmdir "$LOCK_DIR" 2>/dev/null || true
@@ -354,6 +361,36 @@ run_cask_upgrade() {
     return 1
 }
 
+prune_cache_before_today() {
+    local cache_dir cutoff_stamp cutoff_date removed_count
+
+    cache_dir="$(brew --cache)"
+    if [[ ! -d "$cache_dir" || "$cache_dir" == "/" || "$cache_dir" == "$HOME" ]]; then
+        echo "Error: Homebrew returned an unsafe cache path: $cache_dir" >&2
+        return 1
+    fi
+
+    # macOS date -v 使用本地时区。以昨天 23:59:59 为边界，确保今天零点
+    # 之后生成的缓存全部保留，而不是使用滚动 24 小时窗口。
+    cutoff_stamp="$(date -v-1d '+%Y%m%d2359.59')"
+    cutoff_date="$(date '+%Y-%m-%d')"
+    ACTIVE_CLEANUP_MARKER="$(mktemp "${TMPDIR:-/tmp}/brewup-cleanup-cutoff.XXXXXX")"
+    touch -t "$cutoff_stamp" "$ACTIVE_CLEANUP_MARKER"
+
+    if ! removed_count="$(
+        find "$cache_dir" -mindepth 1 \( -type f -o -type l \) \
+            ! -newer "$ACTIVE_CLEANUP_MARKER" -print -delete \
+            | awk 'END { print NR + 0 }'
+    )"; then
+        echo "Error: failed to prune Homebrew cache by calendar date." >&2
+        return 1
+    fi
+
+    rm -f "$ACTIVE_CLEANUP_MARKER"
+    ACTIVE_CLEANUP_MARKER=""
+    echo "Removed ${removed_count} Homebrew cache file(s) dated before ${cutoff_date}; today's cache was kept."
+}
+
 run_cleanup() {
     local cleanup_days="${HB_CLEANUP_DAYS:-}"
 
@@ -361,7 +398,7 @@ run_cleanup() {
         echo -e "${YELLOW}Cleanup skipped because HB_SKIP_CLEANUP is enabled.${NC}"
         return 0
     fi
-    if is_enabled "${HB_CLEANUP_ALL:-0}"; then
+    if is_enabled "${HB_CLEANUP_ALL:-0}" || [[ "$cleanup_days" == "all" ]]; then
         brew cleanup --prune=all
         return
     fi
@@ -373,7 +410,12 @@ run_cleanup() {
         brew cleanup --prune="$cleanup_days"
         return
     fi
-    brew cleanup
+
+    # 普通 brew cleanup 可能按版本状态删除今天生成的下载，无法严格保留
+    # 今日缓存。这里只让 Homebrew 清理 prefix 中的失效链接，再按自然日
+    # 精确清理缓存文件。
+    brew cleanup --prune-prefix
+    prune_cache_before_today
 }
 
 print_summary() {
@@ -436,14 +478,12 @@ separator
 printf '\n'
 
 separator
-print_header "Step 4: Cleaning up old files and caches"
-if ((overall_status != 0)) && ! is_enabled "${HB_CLEANUP_ON_FAILURE:-0}"; then
-    echo -e "${YELLOW}Cleanup skipped because upgrades failed; cached downloads are preserved for the next retry.${NC}"
-elif ! run_cleanup; then
+print_header "Step 4: Cleaning cache dated before today (keeping today's downloads)"
+if ! run_cleanup; then
     overall_status=1
 fi
 separator
 printf '\n'
 
 print_summary "$overall_status"
-exit "$overall_status"
+exit "$overall_status"