bash-script-validator

Bash 脚本验证器

概述

此技能通过分层检查验证 Bash 和 POSIX shell 脚本：

1. 语法验证（bash -n 或 sh -n）
2. ShellCheck 静态分析（系统二进制文件或备用包装器）
3. 自定义安全性、可移植性和优化检查

请先使用下面的默认流程，仅在环境受限时再采用备用方案。

触发指南

当请求涉及脚本质量、lint、语法检查或 shell 可移植性工作时，请使用此技能。

触发短语

• “验证这个 bash 脚本”
• “检查这个 .sh 文件”
• “找出这个 shell 脚本中的安全问题”
• “为什么这个脚本无法通过 ShellCheck？”
• “让这个脚本符合 POSIX 标准”
• “在 CI 运行前检查这个 shell 脚本”

不触发示例

• 不涉及脚本文件的一般 Linux 命令问题
• 不涉及 shell 脚本的 Kubernetes、Terraform 或流水线验证任务
• 纯文本编辑任务

确定性执行模型

从此技能目录运行命令：

cd devops-skills-plugin/skills/bash-script-validator

步骤 1：预检

1. 确认目标路径存在且可读。
2. 确认 bash 可用。
3. 确定能否直接应用修复（有写入权限），还是只能提出建议（只读）。

步骤 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：提供或应用修复

对于每个问题，请包含：

1. 验证器输出中的准确位置（行号和代码片段）
2. 根本原因
3. 修正后的代码
4. 此更改为何更安全或更具可移植性
5. 小节级引用（格式如下）

如果请求包含修补文件，且有写入权限，请按问题类型分组，分批应用修复。

步骤 5：重新运行策略（更改后必须执行）

每批编辑后都要重新运行验证器：

bash scripts/validate.sh <script-path>

重新运行循环规则：

1. 持续运行，直到没有引入新的错误。
2. 如果有意保留警告，请说明接受这些警告的原因。
3. 如果因限制而无法彻底解决问题，请报告未解决事项并给出明确的后续操作。
4. 始终报告最近一次重新运行的退出代码和剩余问题数量。

备用行为

仅当默认流程无法按原样运行时，才使用以下分支。

限制	备用操作	报告要求
缺少 shellcheck，但有包装器可用	让 scripts/validate.sh 自动使用 scripts/shellcheck_wrapper.sh --cache	说明使用了包装器模式
shellcheck 和包装器都不可用	仅运行语法和自定义检查（验证器会执行这些检查）	明确说明覆盖范围有所缩减且缺少 ShellCheck 分析
包装器无法使用 Python	跳过包装器路径，保留语法和自定义检查	说明 ShellCheck 无法运行的原因
目标文件为只读	提供准确的补丁建议，不编辑文件	将回复标注为“仅提供建议”
目标文件不存在或不可读	停止并请求有效的文件路径	不得捏造结果
输入为二进制或非文本文件	停止验证	报告不支持的输入类型

修复的引用指南

每项非简单修复都必须引用具体小节。

必需的引用格式：

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

引用规则：

1. 引用能够证明该修复合理的最具体小节。
2. 对于 ShellCheck 发现的问题，同时注明 SC#### 代码和对应小节。
3. 如果没有完全匹配的小节，则引用最接近的小节，并说明该修复是根据该指南推断得出的。

响应模板

使用以下结构生成确定性输出：

• 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 可用后必须重新验证的内容。

验证器脚本详情

脚本

• scripts/validate.sh：主要验证器入口
• scripts/shellcheck_wrapper.sh：可选的 ShellCheck 回退方案，使用缓存的 Python 虚拟环境

检测与顺序

scripts/validate.sh 中的验证顺序：

1. 文件检查（存在/可读/文本）
2. 根据 Shebang 检测 Shell
3. 语法检查
4. ShellCheck（或回退/跳过处理）
5. 自定义检查
6. 汇总并给出退出代码

退出代码

• 0：未发现问题
• 1：发现警告
• 2：发现错误

参考资料

仅加载所需内容：

• 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

完成标准

满足以下所有条件后，此技能更新才算完成：

1. 明确说明触发指南（包括正向示例和不触发示例）。
2. 默认工作流具有确定性且顺序明确。
3. 明确说明工具缺失和受限环境下的回退行为。
4. 修复说明包含具体小节级别的引用。
5. 必须重新运行修复后的检查，并报告退出代码。
6. 文档同时支持全自动和受限执行路径。