Bash脚本验证器

概览

这个技能提供bash和shell脚本的综合验证，检查语法错误、最佳实践、安全漏洞和性能优化。它能够自动检测脚本是bash还是POSIX sh，基于shebang应用适当的验证规则。

何时使用这个技能

在以下情况下使用这个技能：

验证bash或shell脚本（.sh, .bash文件）
在部署前检查脚本的语法错误
在POSIX sh脚本中识别bashism
查找安全漏洞（不安全的eval，命令注入）
优化脚本性能
确保POSIX合规性
调试shell脚本问题
学习shell脚本最佳实践
代码审查shell脚本

验证能力

1. 语法验证

Bash脚本：使用bash -n验证
POSIX sh脚本：使用sh -n验证
在运行时之前捕获语法错误
报告语法问题的行号

2. ShellCheck集成

全面静态分析
数百个内置检查
严重性级别：错误、警告、信息、风格
特定于shell的验证（bash, sh, zsh, ksh）
为每个问题提供详细文档链接

3. 安全检查

变量使用eval的不安全使用
命令注入漏洞
危险的rm -rf使用
在危险上下文中未引用的变量
缺少输入验证

4. 性能优化

无用的cat使用（UUOC）
低效循环
不必要的子shell
可以合并的多个管道
建议使用内置命令而不是外部命令

5. 可移植性检查（针对sh脚本）

检测bashism（数组、[[ ]]等）
非POSIX结构
在sh脚本中特定于shell的功能
推荐POSIX替代方案

6. 最佳实践

缺少错误处理
未引用的变量
已弃用的语法（反引号）
正确使用set -e、set -u、set -o pipefail
函数定义顺序

快速开始

基本验证

# 验证脚本
bash scripts/validate.sh path/to/script.sh

# 验证器将：
# 1. 从shebang检测shell类型
# 2. 运行语法验证
# 3. 运行ShellCheck（如果安装）
# 4. 运行自定义安全/优化检查
# 5. 生成详细报告

示例输出

========================================
BASH/SHELL SCRIPT VALIDATOR
========================================
文件：myscript.sh
检测到的Shell：bash

[SYNTAX CHECK]
✓ 未发现语法错误（bash -n）

[SHELLCHECK]
myscript.sh:15:5: 警告：引用以防止单词分割 [SC2086]
myscript.sh:23:9: 错误：使用|| exit处理cd失败 [SC2164]

[CUSTOM CHECKS]
⚠ 潜在的命令注入：发现带有变量的eval
  第42行：eval $user_input

ℹ 检测到无用的cat使用
  第18行：cat file.txt | grep pattern

========================================
VALIDATION SUMMARY
========================================
错误：2
警告：3
信息：1

在Claude代码中的使用

当验证shell脚本时，Claude必须遵循以下步骤：

调用验证器对shell脚本文件：
```
bash scripts/validate.sh <script-path>
```
分析结果以识别问题：
- 审查验证器输出中的错误、警告和信息消息
- 注意ShellCheck错误代码（SC####）以供查找
参考文档以获取详细解释：
- 对于ShellCheck代码：阅读docs/shellcheck-reference.md
- 对于常见错误：阅读docs/common-mistakes.md
- 对于bash特定问题：阅读docs/bash-reference.md
- 对于POSIX sh问题：阅读docs/shell-reference.md
建议修复带代码示例：
- 对于发现的每个问题，提供更正后的代码
- 当有帮助时显示前后对比
- 参考验证输出中的具体行号
解释最佳实践来自包含的指南：
- 解释为什么每个修复可以改善脚本
- 引用文档文件中的特定部分

必需的工作流程

用户："检查这个bash脚本是否有问题"

Claude必须：
1. 运行：bash scripts/validate.sh <script-path>
2. 阅读验证输出并识别所有问题
3. 阅读docs/common-mistakes.md以查找修复模式
4. 阅读docs/shellcheck-reference.md以获取SC错误解释（如果需要）
5. 对于每个发现的问题：
   a. 显示有问题的代码
   b. 解释问题（参考文档）
   c. 提供更正后的代码
   d. 解释为什么修复可以改善脚本

示例响应格式

运行验证器后，Claude应该以以下格式响应：

## 验证结果

发现X个错误，Y个警告，Z个信息问题。

### 问题1：未引用变量（第25行）

**问题：**
\`\`\`bash
if [ ! -f $file ]; then  # 单词分割风险
\`\`\`

**参考：** 见`common-mistakes.md`部分"1. 未引用变量"

**修复：**
\`\`\`bash
if [ ! -f "$file" ]; then  # 正确引用
\`\`\`

**为什么：** 未引用变量会经历单词分割和glob扩展，
导致包含空格或特殊字符的文件名出现意外行为。

### 问题2：...

综合文档

核心参考

bash-reference.md

bash特定功能与POSIX sh
参数扩展
数组和关联数组
控制结构
函数和作用域
最佳实践
常见陷阱

shell-reference.md

POSIX sh合规性
可移植结构
与bash的差异
字符类
POSIX实用程序
测试合规性

shellcheck-reference.md

ShellCheck错误代码解释
严重性级别
配置选项
禁用检查
CI/CD集成
编辑器集成

工具参考

grep-reference.md

基本和扩展正则表达式（BRE/ERE）
常见grep模式
性能提示
字符类
脚本实用示例

awk-reference.md

字段处理
内置变量
模式匹配
数组和函数
日志分析示例
CSV/文本处理

sed-reference.md

流编辑基础
替换模式
地址范围
原地编辑
反向引用
常见一行命令

regex-reference.md

BRE与ERE比较
POSIX字符类
元字符和转义
反向引用
常见模式（IP、电子邮件、电话等）
Shell脚本正则表达式示例

common-mistakes.md

25+常见shell脚本错误
现实世界示例
每个错误的结果
正确的解决方案
快速检查清单

示例脚本

位于examples/目录：

good-bash.sh：展示最佳实践的bash脚本
bad-bash.sh：包含常见错误的bash脚本
good-shell.sh：POSIX合规的sh脚本
bad-shell.sh：包含bashism和错误的sh脚本

使用这些作为学习和教学shell脚本的参考。

验证脚本功能

自动Shell检测

验证器从shebang检测shell类型：

#!/bin/bash, #!/usr/bin/env bash → bash
#!/bin/sh, #!/usr/bin/sh → POSIX sh
#!/bin/zsh → zsh
#!/bin/ksh → ksh
#!/bin/dash → dash

多层验证

语法检查：快速基本验证
ShellCheck：全面静态分析（如果安装）
自定义检查：安全和优化模式
报告生成：彩色编码的详细输出

退出代码

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

安装要求

必需

bash或sh（用于运行脚本）

ShellCheck安装选项

验证器自动检测并使用最佳可用的ShellCheck安装： 选项1：系统范围（推荐 - 最快）

# macOS
brew install shellcheck

# Ubuntu/Debian
apt-get install shellcheck

# Fedora
dnf install shellcheck

选项2：自动通过包装器（需要Python）

# 包装器自动在venv中安装shellcheck-py
# 需要：python3和pip3
./scripts/shellcheck_wrapper.sh --cache script.sh

# 缓存位置：~/.cache/bash-script-validator/shellcheck-venv
# 清除缓存：./scripts/shellcheck_wrapper.sh --clear-cache

选项3：手动Python安装

pip3 install shellcheck-py

验证器在没有ShellCheck的情况下工作，但当它可用时提供增强的验证。包装器提供自动安装和缓存，以便后续运行更快。

常见验证场景

场景1：将Bash脚本转换为POSIX sh

# 1. 验证当前bash脚本
bash scripts/validate.sh myscript.sh

# 2. 更改shebang为#!/bin/sh
# 3. 重新验证 - 捕获bashism
bash scripts/validate.sh myscript.sh

# 4. 参考shell-reference.md以获取POSIX替代方案
# 5. 修复bashism（数组 → set --, [[ ]] → [ ],等。）
# 6. 重新验证直到干净

场景2：安全审计

验证器自动检查：

不安全的eval使用
命令注入风险
危险的rm -rf模式
在危险上下文中未引用的变量

参考common-mistakes.md以获取详细解释。

场景3：性能优化

识别：

无用的cat使用（UUOC）
低效的文件读取循环
不必要的外部命令
管道效率低下

参考特定工具的文档（grep, awk, sed）以获得更好的模式。

与开发工作流程集成

提交前钩子

#!/bin/bash
for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.sh$'); do
    if ! bash .claude/skills/bash-script-validator/scripts/validate.sh "$file"); then
        echo "Validation failed for $file"
        exit 1
    fi
done

CI/CD集成

# 例如GitHub Actions
- name: Validate Shell Scripts
  run: |
    find . -name "*.sh" -exec bash .claude/skills/bash-script-validator/scripts/validate.sh {} \;

学习资源

使用包含的文档：

学习bash脚本编写：从bash-reference.md开始
编写可移植脚本：阅读shell-reference.md
掌握文本处理：学习grep, awk, 和 sed参考
理解正则表达式：参考regex-reference.md
避免错误：查看common-mistakes.md
修复问题：在shellcheck-reference.md中查找错误代码

最佳实践

脚本作者

总是包含shebang
使用set -euo pipefail进行严格模式
引用所有变量扩展
检查关键命令的返回代码
使用有意义的变量名
为复杂逻辑添加注释
提交前验证脚本

审核者

在所有脚本上运行验证器
首先检查安全问题
如有需要，验证POSIX合规性
查找性能优化
确保适当的错误处理
验证文档/注释

技术细节

目录结构

bash-script-validator/
├── SKILL.md                    # 这个文件
├── scripts/
│   └── validate.sh             # 主验证脚本
├── docs/
│   ├── bash-reference.md       # Bash功能和语法
│   ├── shell-reference.md      # POSIX sh参考
│   ├── shellcheck-reference.md # ShellCheck错误代码
│   ├── grep-reference.md       # grep模式和使用
│   ├── awk-reference.md        # AWK文本处理
│   ├── sed-reference.md        # sed流编辑
│   ├── regex-reference.md      # 正则表达式
│   └── common-mistakes.md      # 常见陷阱
└── examples/
    ├── good-bash.sh            # 最佳实践示例
    ├── bad-bash.sh             # 反模式示例
    ├── good-shell.sh           # POSIX sh示例
    └── bad-shell.sh            # Bashism示例

验证逻辑

验证器按此顺序执行检查：

文件存在和可读性检查
Shebang检测 → 确定shell类型
语法验证 → 特定于shell（bash -n或sh -n）
ShellCheck验证 → 如果安装，使用适当的shell方言
自定义安全检查 → 模式匹配漏洞
自定义可移植性检查 → sh脚本中的bashism
摘要生成 → 带计数的彩色编码报告

资源

官方文档

内部参考

所有文档都包含在docs/目录中，供离线参考和上下文加载。

注意：这个技能自动加载与验证结果相关的文档，为Claude提供必要的上下文，以有效解释问题和建议修复。