shell-scripter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shell Scripter

Shell脚本工具

Generate, review, convert, and lint shell scripts. Makefile and justfile generation. References ShellCheck rule IDs with explanations but does NOT run ShellCheck.

Scope: Shell scripts (bash, zsh, fish, sh/POSIX), Makefiles, justfiles. NOT for Python scripts (use python-conventions), CI/CD pipelines (use devops-engineer), or running/testing scripts.

生成、审核、转换和检查Shell脚本。支持Makefile和justfile生成。会引用ShellCheck规则ID并提供解释，但不会运行ShellCheck。

适用范围： Shell脚本（bash、zsh、fish、sh/POSIX）、Makefile、justfile。不适用于Python脚本（请使用python-conventions）、CI/CD流水线（请使用devops-engineer）或脚本运行/测试场景。

Dispatch

调度模式

$ARGUMENTS	Mode
`create <description>`	Generate a shell script from natural language
`review <script or path>`	Audit for pitfalls, reference ShellCheck rules
`convert <script or path> <target>`	Dialect conversion (bash/zsh/fish)
`posix <script or path>`	POSIX compliance check at pattern level
`makefile <tasks>`	Generate a Makefile from task descriptions
`justfile <tasks>`	Generate a justfile from task descriptions
Natural language about shell scripting	Auto-detect mode from intent
Empty	Show mode menu with examples

参数	模式
`create <description>`	根据自然语言描述生成Shell脚本
`review <script or path>`	检查脚本陷阱，引用ShellCheck规则
`convert <script or path> <target>`	方言转换（bash/zsh/fish）
`posix <script or path>`	基于模式的POSIX合规性检查
`makefile <tasks>`	根据任务描述生成Makefile
`justfile <tasks>`	根据任务描述生成justfile
关于Shell脚本的自然语言描述	根据意图自动检测模式
空输入	显示带示例的模式菜单

Auto-Detection Heuristic

自动检测规则

Path to
```
.sh
```
/
```
.bash
```
/
```
.zsh
```
/
```
.fish
```
file + modification verb (review, check, fix, audit, lint) -> review
Path to
```
.sh
```
file + "to zsh/fish/bash" -> convert
Path to
```
.sh
```
file + "posix" or "portable" -> posix
"makefile" or "make targets" in input -> makefile
"justfile" or "just recipes" in input -> justfile
Describes desired script behavior -> create
Ambiguous -> ask which mode

```
.sh
```
/
```
.bash
```
/
```
.zsh
```
/
```
.fish
```
文件路径 + 修改类动词（review、check、fix、audit、lint）→ review（审核）
```
.sh
```
文件路径 + "转换为zsh/fish/bash" → convert（转换）
```
.sh
```
文件路径 + "posix"或"portable（可移植）" → posix（POSIX合规检查）
输入中包含"makefile"或"make targets（Make目标）" → makefile（生成Makefile）
输入中包含"justfile"或"just recipes（just配方）" → justfile（生成justfile）
描述所需脚本行为 → create（生成）
意图模糊 → 询问使用哪种模式

Mode: Create

模式：生成

Generate a shell script from a natural language description.

根据自然语言描述生成Shell脚本。

Generation Process

生成流程

Determine target dialect (default: bash)

Run

uv run python scripts/dialect-converter.py --list-features <dialect>

to confirm available features

Write the script with:
- Proper shebang (env-based like
```
env bash
```
  , not hardcoded interpreter paths)
- ```
set -euo pipefail
```
  for bash (equivalent for other dialects)
- Meaningful variable names, quoted expansions
- Error handling for external commands
- Usage function if script accepts arguments

确定目标方言（默认：bash）

运行

uv run python scripts/dialect-converter.py --list-features <dialect>

确认可用特性

编写脚本时需包含：
- 基于env的shebang（如
```
env bash
```
  ，而非硬编码解释器路径）
- bash脚本中添加
```
set -euo pipefail
```
  （其他方言使用等效配置）
- 有意义的变量名、带引号的变量展开
- 外部命令的错误处理
- 若脚本接受参数则添加使用说明函数

Validation

验证

Run

uv run python scripts/script-analyzer.py --stdin <<< "$SCRIPT"

on the generated script

Fix any issues found, present final script

在生成的脚本上运行

uv run python scripts/script-analyzer.py --stdin <<< "$SCRIPT"

修复发现的所有问题，呈现最终脚本

Mode: Review

模式：审核

Audit a shell script for common pitfalls. Reference ShellCheck rule IDs.

检查Shell脚本中的常见陷阱。引用ShellCheck规则ID。

Analysis

分析流程

Read the target script

Run

uv run python scripts/script-analyzer.py <path>

Parse the JSON output:

{shebang, dialect, issues, posix_compatible, complexity_estimate}

For each issue, load
```
references/shellcheck-rules.md
```
to explain the rule ID

读取目标脚本

运行

uv run python scripts/script-analyzer.py <path>

解析JSON输出：

{shebang, dialect, issues, posix_compatible, complexity_estimate}

针对每个问题，加载
```
references/shellcheck-rules.md
```
解释规则ID

Findings Report

检查结果报告

Group findings by severity: error > warning > info > style
Present findings with:
- ShellCheck rule ID (e.g., SC2086)
- Line number and code snippet
- Explanation of WHY it is a problem
- Concrete fix
If no issues found, state this explicitly

Severity mapping:

Severity	Examples
error	Unquoted variables in conditionals, syntax errors, command injection
warning	Missing error handling, unquoted glob expansions, deprecated syntax
info	Suboptimal patterns, unnecessary subshells, redundant commands
style	Inconsistent quoting, missing shellcheck directives, naming

按严重程度分组结果：错误 > 警告 > 信息 > 风格
呈现结果时包含：
- ShellCheck规则ID（如SC2086）
- 行号和代码片段
- 问题原因说明
- 具体修复方案
若未发现问题，需明确说明

严重程度映射：

严重程度	示例
错误	条件判断中未加引号的变量、语法错误、命令注入
警告	缺少错误处理、未加引号的通配符展开、已弃用语法
信息	非最优模式、不必要的子shell、冗余命令
风格	不一致的引号使用、缺少shellcheck指令、命名问题

Mode: Convert

模式：转换

Convert shell syntax between bash, zsh, and fish.

Read the source script
Identify source dialect (from shebang or
```
--from
```
flag)

Run

uv run python scripts/dialect-converter.py <path> --from <source> --to <target>

Parse the JSON output:
```
{converted_script, changes, warnings}
```
Present the converted script with a change summary table
Flag any constructs that have no direct equivalent in the target dialect

在bash、zsh和fish之间转换Shell语法。

读取源脚本
识别源方言（从shebang或
```
--from
```
标志获取）

运行

uv run python scripts/dialect-converter.py <path> --from <source> --to <target>

解析JSON输出：
```
{converted_script, changes, warnings}
```
呈现转换后的脚本及变更汇总表
标记目标方言中无直接等效语法的结构

Mode: POSIX

模式：POSIX合规检查

Check a script for POSIX compliance at the pattern level.

Read the target script

Run

uv run python scripts/script-analyzer.py <path> --posix

Identify bash-isms:
```
[[ ]]
```
,
```
(( ))
```
, arrays,
```
local
```
,
```
source
```
, process substitution,
```
{a..z}
```
,
```
$'...'
```
For each bash-ism, suggest the POSIX equivalent from
```
references/posix-compatibility.md
```
Report whether the script is POSIX-compatible or list required changes

基于模式检查脚本的POSIX合规性。

读取目标脚本

运行

uv run python scripts/script-analyzer.py <path> --posix

识别bash特有语法：
```
[[ ]]
```
、
```
(( ))
```
、数组、
```
local
```
、
```
source
```
、进程替换、
```
{a..z}
```
、
```
$'...'
```
针对每个bash特有语法，从
```
references/posix-compatibility.md
```
中建议POSIX等效写法
报告脚本是否符合POSIX规范，或列出所需修改内容

Mode: Makefile

模式：Makefile生成

Generate a Makefile from task descriptions.

Parse task descriptions from
```
$ARGUMENTS
```
Determine dependencies between tasks
Generate Makefile with:
- ```
.PHONY
```
  declarations for non-file targets
- ```
.DEFAULT_GOAL
```
- ```
help
```
  target using self-documenting pattern (
```
## comments
```
  )
- Consistent variable naming (
```
UPPER_SNAKE_CASE
```
  )
- ```
.ONESHELL
```
  when multi-line recipes need shared state
Follow conventions from
```
references/makefile-justfile.md
```

根据任务描述生成Makefile。

解析
```
$ARGUMENTS
```
中的任务描述
确定任务间的依赖关系
生成的Makefile需包含：
- 非文件目标的
```
.PHONY
```
  声明
- ```
.DEFAULT_GOAL
```
- 使用自文档化模式的
```
help
```
  目标（
```
## 注释
```
  ）
- 一致的变量命名（
```
UPPER_SNAKE_CASE
```
  ）
- 当多行配方需要共享状态时添加
```
.ONESHELL
```
遵循
```
references/makefile-justfile.md
```
中的约定

Mode: Justfile

模式：justfile生成

Generate a justfile from task descriptions.

Parse task descriptions from
```
$ARGUMENTS
```
Generate justfile with:
- Recipe documentation comments
- Default recipe (first position or
```
default
```
  alias)
- Parameter declarations with defaults where sensible
- ```
set shell
```
  directive if non-default shell needed
- ```
set dotenv-load
```
  if environment variables are referenced
Follow conventions from
```
references/makefile-justfile.md
```

根据任务描述生成justfile。

解析
```
$ARGUMENTS
```
中的任务描述
生成的justfile需包含：
- 配方文档注释
- 默认配方（第一个位置或
```
default
```
  别名）
- 带默认值的参数声明（合理情况下）
- 若需要非默认Shell则添加
```
set shell
```
  指令
- 若引用环境变量则添加
```
set dotenv-load
```
遵循
```
references/makefile-justfile.md
```
中的约定

Canonical Vocabulary

规范术语

Use these terms exactly throughout:

Term	Definition
dialect	Shell language variant: bash, zsh, fish, sh (POSIX)
bash-ism	Syntax or feature not in POSIX sh (e.g., arrays, `[[ ]]` )
shebang	`#!` line specifying the interpreter
SC rule	A ShellCheck rule ID (e.g., SC2086 = unquoted variable)
recipe	A justfile target (not "task" or "rule")
target	A Makefile target (not "task" or "recipe")
portable	Works across bash/zsh/sh without modification

全程严格使用以下术语：

术语	定义
dialect（方言）	Shell语言变体：bash、zsh、fish、sh（POSIX）
bash-ism（bash特有语法）	POSIX sh中不存在的语法或特性（如数组、 `[[ ]]` ）
shebang	指定解释器的 `#!` 行
SC规则	ShellCheck规则ID（如SC2086 = 未加引号的变量）
recipe（配方）	justfile目标（不使用"task"或"rule"）
target（目标）	Makefile目标（不使用"task"或"recipe"）
portable（可移植）	无需修改即可在bash/zsh/sh中运行

Reference Files

参考文件

Load ONE reference at a time. Do not preload all references into context.

File	Content	Read When
`references/shellcheck-rules.md`	Top 50 ShellCheck rules with severity, explanation, examples, fixes	Review mode, explaining SC rule IDs
`references/posix-compatibility.md`	POSIX builtins, bash-isms with POSIX equivalents, portability patterns	POSIX mode, create mode with `--posix`
`references/dialect-differences.md`	Syntax differences between bash/zsh/fish with conversion recipes	Convert mode, cross-dialect questions
`references/common-pitfalls.md`	Unquoted vars, missing error handling, injection, race conditions, traps	Review mode, create mode best practices
`references/makefile-justfile.md`	Makefile best practices, justfile syntax and patterns, migration guide	Makefile mode, justfile mode

Script	When to Run
`scripts/script-analyzer.py`	Review and POSIX modes -- static analysis of shell scripts
`scripts/dialect-converter.py`	Convert mode -- syntax conversion between dialects

每次仅加载一个参考文件。请勿预先将所有参考文件加载到上下文。

文件	内容	读取时机
`references/shellcheck-rules.md`	前50个ShellCheck规则，包含严重程度、解释、示例、修复方案	审核模式，解释SC规则ID时
`references/posix-compatibility.md`	POSIX内置命令、bash特有语法的POSIX等效写法、可移植模式	POSIX模式、带 `--posix` 参数的生成模式
`references/dialect-differences.md`	bash/zsh/fish之间的语法差异及转换方法	转换模式、跨方言问题查询时
`references/common-pitfalls.md`	未加引号的变量、缺少错误处理、注入、竞争条件、陷阱	审核模式、生成模式最佳实践
`references/makefile-justfile.md`	Makefile最佳实践、justfile语法与模式、迁移指南	Makefile模式、justfile模式

脚本	运行时机
`scripts/script-analyzer.py`	审核和POSIX模式 -- Shell脚本静态分析
`scripts/dialect-converter.py`	转换模式 -- 方言间语法转换

Critical Rules

核心规则

Never claim to run ShellCheck -- reference SC rule IDs and explain them, but analysis is pattern-based
Always use env-based shebangs (e.g.,
```
env bash
```
), never hardcoded interpreter paths
Default to
```
set -euo pipefail
```
in generated bash scripts -- omit only with explicit justification
Always quote variable expansions unless splitting is intentionally required (SC2086)
Never generate scripts that use
```
eval
```
unless no alternative exists -- explain the risk
Every generated script must include error handling for external commands
Generated Makefiles must include a
```
.PHONY
```
declaration and a
```
help
```
target
Generated justfiles must have a default recipe and documentation comments
Review findings must include the SC rule ID, line number, and a concrete fix
Never modify the script being reviewed -- review is read-only
Convert mode must warn about constructs with no direct equivalent in the target dialect
POSIX mode must identify every bash-ism and provide a POSIX alternative

切勿声称运行ShellCheck -- 仅引用SC规则ID并解释，分析基于模式匹配
始终使用基于env的shebang（如
```
env bash
```
），绝不使用硬编码解释器路径
生成bash脚本时默认添加
```
set -euo pipefail
```
-- 仅在有明确理由时省略
除非有意需要拆分，否则始终对变量展开加引号（SC2086）
除非无替代方案，否则绝不生成使用
```
eval
```
的脚本 -- 需解释其风险
每个生成的脚本必须包含外部命令的错误处理
生成的Makefile必须包含
```
.PHONY
```
声明和
```
help
```
目标
生成的justfile必须有默认配方和文档注释
审核结果必须包含SC规则ID、行号和具体修复方案
绝不修改被审核的脚本 -- 审核为只读操作
转换模式必须警告目标方言中无直接等效语法的结构
POSIX模式必须识别所有bash特有语法并提供POSIX替代写法