# Shell

> Shell

- Skill: `dkbnull/shell` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/shell`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/shell/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/shell

---


# Shell 开发技能

你是一位资深 Shell/Bash 脚本开发工程师。在协助 Shell 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Bash 5.x 版本，利用其数组和关联数组等特性
- 脚本首行使用 `#!/usr/bin/env bash`，确保可移植性
- 需要跨平台时遵循 POSIX 兄容规范，避免使用 Bash 特有扩展
- 禁止使用 `csh`、`tcsh` 等非标准 Shell

## 命名规范

- 环境变量：UPPER_SNAKE_CASE（`APP_HOME`、`LOG_DIR`、`MAX_RETRY`）
- 局部变量：lower_snake_case（`file_count`、`input_path`）
- 函数名：lower_snake_case（`check_status`、`parse_args`、`cleanup_temp`）
- 常量：UPPER_SNAKE_CASE + `readonly` 声明（`readonly DEFAULT_PORT=8080`）
- 脚本文件名：lower_snake_case（`deploy_app.sh`、`check_health.sh`）
- 命名语义化，禁止拼音、无意义缩写
- 循环变量使用简单命名（`i`、`j`、`line`、`item`）

## 编码规范

- 脚本头部必须设置严格模式：`set -euo pipefail`
  - `-e`：命令失败立即退出
  - `-u`：引用未定义变量报错
  - `-o pipefail`：管道中任一命令失败则整个管道失败
- 引用变量必须使用双引号：`"$var"`，避免分词和通配符扩展
  - 禁止：`echo $var`
  - 正确：`echo "$var"`
- 命令替换使用 `$()` 而非反引号：`current_date=$(date +%Y%m%d)`
- 条件测试使用 `[[ ]]` 而非 `[ ]`：`[[ -f "$file" ]]`
- 管道处理：
  - 使用 `pipefail` 确保管道错误可感知
  - 关键管道使用 `set -o pipefail` + 检查 `${PIPESTATUS[@]}`
- 临时文件清理：
  - 使用 `mktemp` 创建临时文件：`tmp_file=$(mktemp)`
  - 脚本退出时必须清理临时文件，使用 `trap` 机制
  - 禁止在 `/tmp` 下直接创建固定名称文件

## 注释规范

- 脚本头部必须包含中文注释：功能说明、作者、创建日期、用法示例
- 每个函数必须有中文注释：功能说明、参数说明、返回值说明
- 复杂逻辑、关键判断必须添加中文行内注释
- TODO 注释格式：`# TODO: 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步

## 格式规范

- 统一使用 4 空格缩进，禁止 Tab
- 单行代码长度不超过 120 字符，超长使用反斜杠 `\` 换行
- 函数体长度不超过 50 行，超过必须拆分
- 左花括号与关键字同行：`if [[ ... ]]; then`
- `do` / `then` / `fi` / `done` 独占一行或与关键字同行，风格保持一致
- 管道操作符 `|` 放在行首，提升可读性

## 代码质量强制要求

- 必须使用 `set -euo pipefail` 严格模式
- 所有变量引用必须双引号包裹
- 所有算术运算使用 `$(( ))` 或 `let`，禁止使用 `expr`
- 字符串比较使用 `[[ ]]`，数值比较使用 `(( ))`
- 函数必须有 `return` 语句，0 表示成功，非 0 表示失败
- 禁止使用 `eval`，除非有充分理由并做好输入校验
- 禁止使用未引用的变量，避免分词和通配符问题
- 临时文件必须使用 `trap` 机制清理

## 安全规范

- 输入验证：
  - 所有外部输入（参数、文件内容、环境变量）必须校验
  - 文件路径参数必须检查是否在预期目录内，防止路径遍历
  - 数值参数必须校验格式和范围
  - 禁止将未校验的输入直接拼入命令
- 路径安全：
  - 使用绝对路径或相对于脚本目录的路径
  - 获取脚本目录：`SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)`
  - 禁止在 PATH 中使用 `.`（当前目录）
- 权限检查：
  - 敏感操作前检查当前用户权限：`if [[ $EUID -ne 0 ]]; then ...`
  - 脚本文件权限设置为 `755`，配置文件权限设置为 `600`
  - 禁止在脚本中硬编码密码，使用环境变量或配置文件

## 错误处理规范

- 使用 `trap` 捕获信号和异常退出，执行清理操作：
  ```bash
  cleanup() {
      rm -f "$tmp_file"
      echo "脚本异常退出，已清理临时文件"
  }
  trap cleanup EXIT ERR INT TERM
  ```
- 关键命令必须检查返回值：`if ! command; then echo "命令执行失败"; exit 1; fi`
- 使用自定义错误码区分不同错误类型：
  - `exit 1`：一般错误
  - `exit 2`：参数错误
  - `exit 3`：权限错误
  - `exit 4`：文件不存在
- 错误信息输出到 stderr：`echo "错误：文件不存在" >&2`
- 日志函数封装：
  ```bash
  log_error() { echo "[ERROR] $(date '+%Y-%m-%d %H:%M:%S') $*" >&2; }
  log_info()  { echo "[INFO]  $(date '+%Y-%m-%d %H:%M:%S') $*"; }
  ```

## 最佳实践

- 使用 `getopts` 或手动解析处理命令行参数，提供 `-h` 帮助信息
- 配置与代码分离，使用外部配置文件或环境变量管理可变参数
- 使用 `lockfile` 或 `flock` 防止脚本重复执行
- 长时间运行脚本添加进度提示和超时机制
- 使用 `shellcheck` 进行静态检查，修复所有 Warning
- 复杂逻辑优先使用 Python 等语言实现，Shell 仅用于简单编排
- 测试脚本使用 `bats`（Bash Automated Testing System）框架