用途
bash-scaffold 用于在用户开始编写新的 shell 脚本时，一次性生成结构良好、带安全模板的单个自包含 bash 脚本。用户可能以“scaffold a bash script”“给我一个模板”“为某个任务新建 .sh”或直接描述一个计划用 bash 自动化的杂务来表达需求。如果用户是在编辑已有脚本，或只需要一行 shell 片段，则该技能不适用。
主要能力
生成器从精选模板出发，融合了三方面内容：ralish/bash-script-template 的安全模式、Google Shell 风格指南的格式规则，以及从 Open Color 调色板取色、经 24 位 ANSI 转义实现的颜色方案。模板中的每个可选功能都由形如 # >>> OPTIONAL: <feature-name> <<< 与 # <<< OPTIONAL: <feature-name> >>> 的分区标记包围，每个标记块可整体移除，标记也可干净嵌套。模板中现有的功能名包括：cron-mode、lock、colors、verbose、superuser、check-binary、dry-run。
使用方式
整个流程分为五步，其中只有第 2、3 步会打断用户，其余步骤无需提示直接执行。
第 1 步——捕获脚本用途。读取用户请求，脚本用途即用户所述该脚本将做什么。若请求含糊（只说了“一个 bash 脚本”而无细节），先提一个自由文本澄清问题，因为用途会写入文件头部并影响占位函数体。若用户未提供脚本名，可根据用途挑选一个合理名称：蛇形命名，若脚本将放在 PATH 上则不带扩展名，否则用 .sh 扩展名。仅当存在真实歧义时才与用户确认名称与路径；否则说明选择并继续。
第 2 步——第一轮塑形：运行时上下文。通过一次 AskUserQuestion 调用提出四个问题，每个问题的 header 需在 12 字符以内（这是该调用的限制）。问题包括：脚本在哪里运行（Runtime：仅交互式终端 / cron 任务（除非出错否则静默）/ CI/CD 流水线 / 混合或通用）；需要什么权限（Privileges：无——以调用用户身份运行 / 可通过 sudo 对部分命令提权 / 从一开始就需要 root / 拒绝以 root 运行）；哪种 CLI 形态合适（CLI shape：仅标志（-h、-v、--foo）/ 子命令（动宾模式）/ 位置参数 / 直接运行（完全没有参数））；是否输出彩色文本（Colors：是，并带 --no-color 标志与 NO_COLOR 支持（推荐）/ 始终开启，无标志 / 从不使用颜色）。
第 3 步——第二轮塑形：可选功能。再发出一次 AskUserQuestion 调用，含两个问题。其一为应接哪些可选功能（Features，多选）：单实例锁（防止两个副本同时运行）、外部依赖检查（预先验证所需二进制）、详细/安静日志模式、试运行模式（打印动作而非执行）。其二为正常输出去向（Output）：结果到 stdout、日志到 stderr（推荐默认）/ 另加日志文件（--log path）/ 除非出错否则静默（适合 cron）。若用户在第一轮选了 cron 任务，第二问应将“除非出错否则静默”作为推荐项。
第 4 步——将答案映射到模板功能并组装脚本。读取 assets/template.sh，依据答案构建保留集合：Runtime 为 Cron job 保留 cron-mode；Runtime 为 Mixed / general purpose 保留 cron-mode、verbose；Privileges 为 May escalate via sudo 保留 superuser、check-binary；Privileges 为 Requires root from the start 保留 superuser、check-binary；CLI shape 为 Subcommands 或 Positional args 时不加额外标记，而是调整 parse_params；Colors 为 Yes with --no-color 或 Always on 保留 colors；Colors 为 Never use color 时删除 colors 及所有对 C_* 变量的引用；Features 对应保留 lock、check-binary、verbose、dry-run。对模板中每个 OPTIONAL 块（包括 script_usage heredoc 内的块）应用规则：若功能不在保留集合中，删除从 # >>> OPTIONAL: <name> <<< 行到匹配的 # <<< OPTIONAL: <name> >>> 行之间的整段（含两端）；若在保留集合中，只删除标记行本身，保留其间内容（否则 --help 输出中会打印字面标记文本）。随后删除模板第 8–14 行的“Section markers”说明性注释块。删除后进行按形态调整：子命令形态下，将 parse_params 函数体替换为对 ${1-} 的分发，分派到以各子命令命名的函数，并为示例子命令加一个桩和一个 cmd_help() 函数，保留全局 --help/-h。位置参数形态下，parse_params 仍作标志解析器，但在 while 循环后新增将位置参数收录进 positional=("$@") 数组的检查，并在头部记录预期数量。无参数形态下，从 main 中删除 parse_params 调用及其函数本身，调整 script_usage 以记录该脚本无选项。拒绝以 root 运行时，删除 superuser 块，并在 main 顶部附近加入检查：if [[ ${EUID} -eq 0 ]]; then script_exit 'This script must not be run as root.' 1; fi。始终开启颜色（无标志）时，从 parse_params 与 script_usage 删除 --no-color 标志处理，但保留 color_init 函数体与 NO_COLOR 环境检查。从不使用颜色时，除删除 colors 块外，还将存留脚本中每一处 ${C_-} 或 ${C_} 引用替换为空字符串，并在原仅用于颜色转义的 %b 处将 printf '%b\n' 替换为 printf '%s\n'。另加日志文件时，在 parse_params 中新增 --log <path> 标志，将路径存入 log_file 全局变量，并在 color_init 之后加 exec > >(tee -a "${log_file}") 2>&1，由 [[ -n ${log_file-} ]] 保护。替换头部占位符：{{SCRIPT_PURPOSE}} 为第 1 步的一句话用途；{{AUTHOR}} 若未知则问用户一次，可用时默认取 git config user.name 的值；{{DATE}} 为当天 ISO 日期，例如 2026-05-12。将 main 中位于 ----- replace the lines below with the real work ----- 标记与结尾大括号之间的内容替换为最小桩，提示用户下一步要写什么，并保留该标记注释作为指引。
第 5 步——写出文件、设置可执行位、做健全性检查。将组装好的脚本写到用户请求的路径（或所选默认路径）。写入后执行 chmod +x <path>。若 shellcheck 在 PATH 中，运行 shellcheck <path> 并报告发现的问题；除非用户要求，不因发现而修改脚本，只报告并让用户决定。若 bash -n 可用，运行它作为仅语法解析检查并报告错误。向用户展示最终路径、可执行位、shellcheck 结论（干净 / N 条发现）以及包含哪些功能的一行摘要。到此为止，不再提议后续改动。
适用场景
当用户要开始一个新 shell 脚本并希望样板做得规范时使用，覆盖从交互式终端工具、cron 任务、CI/CD 流水线到通用混合用途的脚本，支持仅标志、子命令、位置参数或无参数等多种 CLI 形态，并可按需接入单实例锁、外部依赖检查、详细/安静日志、试运行模式、日志文件等功能。
限制与注意事项
模板遵循 Google Shell 风格指南：两空格缩进、带花括号的变量展开（${var}）、优先使用 [[ … ]] 而非 [ … ]、优先 $(…) 而非反引号、函数定义用 name() 形式、函数作用域变量用 local。编辑时须保持这些约定，即使用户其他脚本使用四空格缩进，除非用户明确要求。严格模式序言（set -o errexit、nounset、pipefail、errtrace）依据脚本是被执行还是被 source 而有条件启用，不要移动此门控，因为被 source 的严格模式会改变调用方的 shell 选项。颜色为取自 Open Color 调色板的 24 位 ANSI 转义，而非上游模板的旧 8 色集，映射记录于 references/opencolors-palette.md；默认提供六个语义角色：C_ERROR、C_WARN、C_SUCCESS、C_INFO、C_HINT、C_HEADER；当 stdout 不是 TTY、设置了 NO_COLOR 或传入 --no-color 时，模板安全降级为无颜色。若用户日后要求换色，查阅参考文件中的调色板表选取对应十六进制，前景色输出为 \033[38;2;R;G;Bm，背景色为 \033[48;2;R;G;Bm。分区标记是模板契约，删除功能块时也要删除标记；日后新增可选功能时，用相同的 >>> OPTIONAL: <name> <<< 与 <<< OPTIONAL: <name> >>> 形式包围，以便下一轮脚手架能识别。生成器不会提交脚本、不会编辑所选输出路径之外的任何内容、不会安装依赖或运行脚本、不会改写用户的 .bashrc 或 shell 配置；若用户需要这些，须先询问。参考文件包括 assets/template.sh（带分区标记的源模板）与 references/opencolors-palette.md（调色板映射、十六进制目录及选择 24 位 ANSI 的理由）。