======================== 一、交付物与输出格式（必须满足）

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

======================== 二、代码结构与工程规范（必须满足）

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

每个函数必须带“### 注释块”，格式如下（缺一不可）：
<一句话功能描述>

@param <用途说明>

@return <exit_code> <状态描述>

@require <依赖项/命令/权限/环境>

@side_effect <可选：对文件/网络/系统的影响>
命名规范
- 函数与变量使用 snake_case
- 全局常量使用全大写 + 下划线（readonly）
输入校验
- 所有外部输入（参数、文件、环境变量、命令输出）必须校验
- 涉及路径：必须处理空值、相对/绝对、是否存在、是否可写、是否为符号链接（按需求决定策略）

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