Bash Script Validator 用于校验、lint、审计或修复 bash/shell/.sh 脚本，核心依托 ShellCheck。
用途
该技能面向脚本质量、lint、语法检查和 shell 可移植性工作。触发场景包括：验证 bash 脚本、lint .sh 文件、查找 shell 脚本中的安全问题、排查脚本为何未通过 ShellCheck、使脚本符合 POSIX、在 CI 前审查 shell 脚本。非触发场景包括：不涉及脚本文件的通用 Linux 命令问题、不涉及 shell 脚本的 Kubernetes/Terraform/管道校验任务、纯文字编辑任务。
主要能力
校验采用分层检查：语法验证（bash -n 或 sh -n）；ShellCheck 静态分析（系统二进制或包装脚本回退）；自定义的安全、可移植性和优化检查。
检测与顺序：scripts/validate.sh 中的校验顺序为文件检查（存在/可读/文本）、基于 shebang 的 shell 检测、语法检查、ShellCheck（或回退/跳过行为）、自定义检查、带退出码的摘要。
退出码：0 表示未发现问题；1 表示发现警告；2 表示发现错误。
使用方式
从技能目录运行命令： cd devops-skills-plugin/skills/bash-script-validator
第 1 步：预处理。确认目标路径存在且可读；确认 bash 可用；判断修复能否直接应用（有写权限）还是只能建议（只读）。
第 2 步：运行基线校验（默认路径）： bash scripts/validate.sh <script-path>
如需确定性的阶段行为，可显式设置 ShellCheck 提供方：
Modes: auto (default), system, wrapper, disabled
VALIDATOR_SHELLCHECK_MODE=system bash scripts/validate.sh <script-path>
记录：检测到的 shell 类型；退出码（0 干净，1 警告，2 错误）；所有报告的问题行及存在时的 ShellCheck 代码（SC####）。
第 3 步：只加载需要的参考文档。按问题类型渐进披露：ShellCheck 代码说明见 docs/shellcheck-reference.md；通用修复模式与安全错误见 docs/common-mistakes.md；Bash 专有行为见 docs/bash-reference.md；POSIX 可移植性或 bashism 修复见 docs/shell-reference.md；文本处理优化问题见 docs/grep-reference.md、docs/awk-reference.md、docs/sed-reference.md、docs/regex-reference.md（仅在直接相关时）。
第 4 步：提供或应用修复。每个问题需包含：来自校验器输出的准确位置（行号和片段）；根因；修正后的代码；该改动为何更安全或更可移植；子章节级引用。若请求包含补丁文件且具备写权限，按问题类型分组小批量应用修复。
第 5 步：变更后强制重新运行。每批编辑后重新运行校验器： bash scripts/validate.sh <script-path>
重跑循环规则：持续进行，直到不再引入新错误；若警告为设计所留，记录为何有意接受；若受约束无法完全解决，报告未解决项并给出明确后续动作；始终报告最新一次重跑的退出码和剩余问题数。
回退行为
仅在默认流程无法按原样运行时使用以下分支。 shellcheck 缺失但包装脚本可用：让 scripts/validate.sh 自动使用 scripts/shellcheck_wrapper.sh --cache；说明使用了包装脚本模式。 shellcheck 与包装脚本都不可用：只运行语法 + 自定义检查（校验器会这样做）；明确说明覆盖范围缩小、缺少 ShellCheck 分析。 Python 不可用导致包装脚本无法运行：跳过包装脚本路径，保留语法 + 自定义检查；说明 ShellCheck 无法运行的原因。 目标文件只读：提供精确补丁建议而不编辑；将回复标记为“advisory only”。 目标文件缺失或不可读：停止并要求提供有效文件路径；不得编造结果。 二进制/非文本输入：停止校验；报告不支持的输入类型。
修复的引用规范
对每个非平凡修复使用子章节级引用。格式： Reference: docs/<file>.md -> <Section> -> <Subsection> 示例： Reference: docs/common-mistakes.md -> 1. Unquoted Variables -> Solution Reference: docs/shellcheck-reference.md -> SC2164: Use || exit After cd Reference: docs/shell-reference.md -> POSIX Best Practices -> 5. Avoid Bashisms 引用规则：引用最能支撑该修复的具体章节；对 ShellCheck 发现，同时包含 SC#### 代码和匹配章节；若不存在确切子章节，引用最接近的章节并说明该修复是由此指导推断而来。
响应模板
使用以下结构保证确定性输出： Validation Results Command: bash scripts/validate.sh <script-path> Detected shell: <shell> Exit code: <code> Summary: <errors> errors, <warnings> warnings, <info> info Issue: <short label> (Line <n>) Problem: <problematic snippet> Fix: <corrected snippet> Why: <short explanation> Reference: docs/<file>.md -> <Section> -> <Subsection> Rerun command: bash scripts/validate.sh <script-path> Exit code after fixes: <code> Remaining issues: <count or none>
示例流程
全自动环境：
1) Baseline validation
bash scripts/validate.sh examples/bad-bash.sh
2) Apply fixes to target script
3) Rerun validation
bash scripts/validate.sh examples/bad-bash.sh 预期行为：完整的语法 + ShellCheck + 自定义检查覆盖，并迭代重跑直至稳定。
确定性 CI 门禁：
Requires a system shellcheck binary.
bash scripts/run_ci_checks.sh 该运行器强制 VALIDATOR_REQUIRE_SHELLCHECK=1 和 VALIDATOR_SHELLCHECK_MODE=system，因此若 ShellCheck 阶段被跳过或不可用，CI 会失败。
受限环境（无 ShellCheck 运行时）：
shellcheck unavailable and wrapper cannot run
bash scripts/validate.sh examples/bad-shell.sh 预期行为：语法 + 自定义检查仍会运行；报告覆盖范围缩小，并列出 ShellCheck 可用后必须重新校验的内容。
适用场景与限制
适用场景包括脚本质量检查、CI 前审查、安全问题发现、POSIX 可移植性修复。限制与约束：缺少 shellcheck 时覆盖范围缩小；二进制/非文本输入不支持；目标文件只读时仅提供建议；目标文件缺失或不可读时停止且不编造结果。
脚本细节
Scripts：scripts/validate.sh 为主校验入口；scripts/shellcheck_wrapper.sh 为可选的 ShellCheck 回退，使用缓存的 Python 虚拟环境。
参考文档
按需加载：docs/bash-reference.md、docs/shell-reference.md、docs/shellcheck-reference.md、docs/common-mistakes.md、docs/grep-reference.md、docs/awk-reference.md、docs/sed-reference.md、docs/regex-reference.md。
完成标准
当以下条件全部满足时本技能更新完成：触发指导明确（含正向与非触发示例）；默认工作流确定性且有顺序；对缺失工具与受限环境的回退行为明确；修复说明包含子章节级引用；修复后重跑策略为强制并报告退出码；文档同时支持全自动与受限执行路径。