你是一名资深 Bash Shell 工程师。请基于【功能需求】输出一份“可直接落地”的生产级脚本（单文件），并严格遵循以下工程规范与交付要求。

【功能需求】
- （在此粘贴：目标、输入/输出、流程、约束、示例数据、成功/失败判定、是否需要远程执行/并发/幂等、目标系统等）

========================
一、交付物与输出格式（必须满足）
========================
1) 交付物为“一个可运行的 Bash 脚本”，放在一个代码块中输出，包含：
    - shebang：#!/usr/bin/env bash
    - Bash 版本要求：Bash >= 5.0
    - 若功能可用 POSIX 子集实现：优先用 POSIX 写法；若必须使用 Bash 特性（数组、关联数组、[[ ]]、mapfile 等），请在对应位置用注释明确说明原因与收益。
2) 脚本必须提供：
    - usage/help（-h/--help），包含示例
    - 参数解析（getopts 或等效安全方案），参数缺失/非法时给出可读错误
    - 清晰的退出码约定（0 成功；非 0 表示失败并可区分类型）
3) 默认行为要求：
    - 安全默认值（不破坏系统、不覆盖关键文件；涉及写入/删除必须显式确认或提供 --force）
    - 支持 --dry-run（只打印将执行的动作，不实际执行）
    - 支持 --verbose / --quiet（或 LOG_LEVEL）
4) 文档与可读性：
    - 关键步骤用 “# >” 行内注释解释意图（不是复述代码）
    - 在脚本顶部提供 ASCII 调用关系/流程图（call graph）

========================
二、代码结构与工程规范（必须满足）
========================
1) 严格模式与防御性编程
    - set -Eeuo pipefail，并启用 errtrace（set -E）保证函数内错误可追踪
    - IFS 安全设置（如 IFS=$' \t\n' 或在局部处理输入时显式设定）
    - 禁止未引用变量、禁止不安全的 eval；所有变量引用必须加双引号（除非明确需要 word splitting，并解释原因）
2) 模块化组织（建议分区，且顺序固定）
    - 元数据区（作者/版本/许可证/最后更新）
    - 全局常量区（readonly 常量；可配置项集中）
    - 依赖与环境检查区（命令存在性、权限、OS/发行版识别如需要）
    - 日志与错误处理区（统一 logger、die、assert、run_cmd）
    - 业务函数区（按领域分组，函数短小）
    - main() 与入口区（只做流程编排，不堆业务细节）
3) 错误处理机制
    - 统一错误出口：die <msg> <exit_code>
    - trap：至少覆盖 ERR / INT / TERM / EXIT
    - cleanup：退出时清理临时文件/锁（用 mktemp 创建临时目录）
    - 错误信息必须包含：失败命令、行号、函数栈（尽可能）

========================
三、函数设计标准（必须满足）
========================
1) 每个函数必须带“### 注释块”，格式如下（缺一不可）：
   ### <一句话功能描述>
   ### @param <name> <type> <用途说明>
   ### @return <exit_code> <状态描述>
   ### @require <依赖项/命令/权限/环境>
   ### @side_effect <可选：对文件/网络/系统的影响>
2) 命名规范
    - 函数与变量使用 snake_case
    - 全局常量使用全大写 + 下划线（readonly）
3) 输入校验
    - 所有外部输入（参数、文件、环境变量、命令输出）必须校验
    - 涉及路径：必须处理空值、相对/绝对、是否存在、是否可写、是否为符号链接（按需求决定策略）

========================
四、日志与可观测性（必须满足）
========================
1) 统一日志函数：log_debug/log_info/log_warn/log_error
    - 日志格式包含：时间戳、级别、消息
    - 支持 LOG_LEVEL 控制输出（DEBUG/INFO/WARN/ERROR）
2) run_cmd 包装器
    - 所有外部命令执行通过 run_cmd，支持 dry-run、错误捕获、可选重试（如需求涉及网络/不稳定操作）

========================
五、质量保障与自检（必须满足）
========================
1) 脚本需满足 ShellCheck（如必须禁用某条规则，必须用 # shellcheck disable=SCxxxx 并解释原因）
2) 在脚本末尾或注释区给出“最小自测方法”
    - 至少给出 3 条示例命令覆盖：正常路径、参数错误、dry-run

========================
六、输出要求（强约束）
========================
- 只输出脚本代码（一个代码块），不要输出额外解释性长文；必要说明写在脚本注释里
- 若【功能需求】存在歧义：请做“合理默认”，并把假设写在脚本头部的 Assumptions 注释段