shfmt-formatting（shfmt脚本格式化）Skill 怎么用？如何安装？

shfmt 脚本格式化 Skill：让 shell 脚本风格统一，终结“缩进用什么”的团队争论

它是什么：shfmt-formatting（shfmt 脚本格式化 Skill）是一个面向 shell 脚本格式化的专家知识型技能，技能 ID 为 13849，核心是把 shfmt 的方言支持、格式化模式、编辑器集成、CI 校验和排错经验一次性喂给 AI。
它能做什么：覆盖 POSIX sh、bash、mksh、bats 四种 shell 方言，讲透缩进、间距、函数、case、here-doc、重定向、二元操作符等格式化决策，并给出 VS Code、Vim、Emacs、JetBrains 的落地配置。
它怎么用：用自然语言向 AI 描述你的脚本、方言和团队风格，技能会给出可直接照抄的命令与配置片段；再用 -d 预览、-w 就地写入、-l 列出待改文件。
适合谁：DevOps/SRE、后端与运维开发、写部署脚本和 CI 流水线的工程师，以及需要统一团队脚本风格的技术负责人。
一句话价值：把“脚本风格靠自觉”变成“脚本风格靠工具”，让格式问题在提交前就被自动拦下。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

这个技能的中文名是 shfmt脚本格式化Skill，英文名是 shfmt-formatting，技能 ID 为 13849。

它解决什么问题？

shell 脚本长期处于“格式化无人管”的地带：有人用 2 个空格缩进，有人用 4 个空格，有人用制表符；有人把 if 和 then 写一行，有人写两行；有人在行尾留一堆多余分号。久而久之，git diff 里混着大量纯风格改动，代码评审时真正的逻辑问题被淹没。shfmt 正是为此而生的格式化器——它把脚本解析成 AST 再以规范格式打印，消除风格争议。而本技能的价值，是把“怎么用对 shfmt”这件事系统化：方言怎么选、参数怎么配、编辑器怎么接、CI 怎么卡、报错怎么排。

需要注意的一个特点

根据技能元信息，该技能标记为「用户可调用: false」，也就是说它不是一个供用户直接敲命令调用的工具型技能，而是以专家知识注入的方式工作：当你在对话中提出“帮我格式化这个 shell 脚本”“shfmt 报解析错误怎么办”“怎么在 VS Code 里保存时自动格式化”这类问题时，AI 会调用这套知识给出专业答案。因此它的“安装”本质是把知识接入你的 AI 工作环境。

一键安装 AI 技能提升开发效率的思路与步骤

确认前提：如果你希望 AI 给出的命令能真正跑起来，本地需要有 shfmt 可执行文件（shfmt 的安装方式请以 shfmt 官方文档说明为准）；若只想先“咨询”格式化方案，则无需本地安装。
找到技能：在所用 AI 工具的技能市场 / 技能库中，按英文名 shfmt-formatting 或技能 ID 13849 检索，具体入口与命令以官方说明为准。
安装并启用：将技能添加到当前工作区或全局技能列表并开启，使 AI 在相关对话中可引用其知识。
验证是否生效：向 AI 提一个只有该技能才好回答的问题，例如“shfmt 的 -i 0 和 -i 2 分别是什么含义？-ci 又控制什么？”。如果回答能准确说明 -i 0 表示用制表符缩进、-i 2 表示 2 空格缩进、-ci 表示 case 分支缩进，说明技能已正常加载。
（可选）验证实操链路：让 AI 给出一条完整命令，然后在本地仓库执行 shfmt -d . 看是否输出差异列表，以此确认“知识 + 工具”闭环打通。

2. 该技能的主要功能和特点

多方言覆盖：明确区分 POSIX Shell（#!/bin/sh，无数组、无 [[ ]]）、Bash（#!/usr/bin/env bash，支持数组、[[ ]]、算术扩展）、mksh（Korn shell 变体，typeset -A 关联数组）、Bats（#!/usr/bin/env bats，@test 语法）四类方言，避免“拿 bash 语法写 /bin/sh”这种经典事故。
格式化模式全清单：缩进统一、操作符与关键字间距规范化、多语句拆分为独立行、here-doc 缩进保留（含 <<- 的制表符剥离语义）、函数定义风格统一、case 分支统一、二元操作符续行、重定向空格处理。
关键参数速查：-i（缩进宽度，0 为制表符）、-ci（case 缩进）、-bn（二元操作符换行）、-sr（重定向加空格）、-fn（函数大括号另起一行）、-ln（强制指定方言）、-d（显示差异）、-l（列出待格式化文件）、-w（就地写入）、-mn（压缩）。
常见问题诊断路径：混合制表符与空格、行尾多余分号、引号风格、超长行、数组单行/多行保留策略，逐条给出“问题—解决方案—前后对比”。
四大编辑器集成配方：VS Code（shell-format 扩展 + settings.json + formatOnSave）、Vim/Neovim（ALE 或 formatprg）、Emacs（reformatter）、JetBrains（Shell Script 插件），每项都给出可直接粘贴的配置。
Git 与 CI 落地：只格式化暂存文件、pre-commit 钩子拦截、格式化自 main 分支以来变更的文件，以及 CI 中使用 shfmt -d 的退出码语义（0 = 无需更改，1 = 需要更改或出错）。
最佳实践与故障排除：保存时格式化、CI 验证、提交 .shfmt.toml 统一团队设置、shell 方言与 shebang 保持一致、格式化后人工复核、不混用风格、预提交钩子防脏提交；解析失败时先用 bash -n / sh -n 检查语法，方言识别错误时用 -ln bash / -ln posix 强制指定。

和普通工具比强在哪？ 普通做法是“装个 shfmt 然后自己翻 man page”，参数记不住、编辑器配置东拼西凑、CI 报错看不懂退出码。这个技能把这些散落知识组织成一条从“选择方言”到“提交钩子”的完整链路，还能针对具体报错给出排查顺序。

3. 如何使用该技能？

第 1 步：明确脚本的方言与 shebang

先看脚本第一行。#!/bin/sh 就走 POSIX 路线，#!/usr/bin/env bash 就走 Bash 路线，#!/usr/bin/env bats 就是测试文件。AI 会据此给出匹配的格式化建议，避免误用扩展语法。

第 2 步：确定团队风格参数

例如输入：“我们团队用 2 空格缩进，case 分支要缩进，&& 要换到下一行，重定向符号后面要空格。”对应参数即 -i 2 -ci -bn -sr。把这句话告诉 AI，它会直接给你成型的命令行。

第 3 步：先用 -d 预览，不要直接改

shfmt -i 2 -ci -bn -sr -d script.sh

-d 输出 diff 并返回退出码，是安全的“只看不改”模式。

第 4 步：确认后再就地写入

shfmt -i 2 -ci -bn -sr -w script.sh
# 或整仓批量
shfmt -i 2 -ci -bn -sr -w .

第 5 步：接入编辑器实现保存即格式化

以 VS Code 为例，安装 shell-format 扩展后在 settings.json 中配置：

{
  "shellformat.path": "/usr/local/bin/shfmt",
  "shellformat.flag": "-i 2 -ci -bn",
  "[shellscript]": {
    "editor.defaultFormatter": "foxundermoon.shell-format",
    "editor.formatOnSave": true
  }
}

第 6 步：接入 Git 与 CI 形成门禁

预提交钩子示例（来自技能知识）：

#!/usr/bin/env bash
if ! command -v shfmt &>/dev/null; then
    echo "shfmt not found, skipping format check"
    exit 0
fi
files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.sh$')
if [ -n "$files" ]; then
    if ! echo "$files" | xargs shfmt -d; then
        echo "Shell scripts need formatting. Run: shfmt -w <files>"
        exit 1
    fi
fi

CI 中则统一执行 shfmt -l . 列出待改文件、shfmt -d . 输出差异，非 0 即失败。

输入示例与输出说明

你的提问	技能给出的输出
“这个脚本缩进全乱了，怎么统一成 2 空格？”	`shfmt -i 2 -w script.sh`，并说明如何用 `-d` 先预览
“shfmt 报解析错误怎么办？”	先用 `bash -n script.sh` 或 `sh -n script.sh` 定位语法错误，再回到 shfmt
“明明是 POSIX 脚本，它却按 bash 处理？”	用 `shfmt -ln posix script.sh` 强制方言
“发布时想去掉注释和空格”	`shfmt -mn script.sh > script.min.sh`，并提醒仅用于分发、不用于开发

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
shfmt（本技能所讲解的本体工具）	shell 脚本专用格式化器	解析 AST 后规范打印，支持 posix/bash/mksh/bats，参数丰富，支持 diff、列文件、就地写入、压缩	需安装 shfmt 可执行文件；参数需学习	团队风格统一、编辑器保存格式化、CI 格式门禁	优势：专为 shell 设计、方言识别准、速度快、可压缩；不足：不自动换行长行，不支持行内忽略注释，只管格式不管逻辑缺陷
ShellCheck	shell 脚本静态检查工具	检测语法陷阱、引号误用、不可移植写法等逻辑与健壮性问题	需单独安装；有在线版与编辑器插件	代码评审前的质量扫描	优势：能发现真正的 bug；不足：不做格式化，与 shfmt 是互补而非替代关系
beautysh / 通用美化脚本	轻量格式化脚本	主要调整缩进与基础排版	安装简单	小规模脚本的快速整理	优势：上手快；不足：方言识别弱、规则可选性少、对 here-doc 与复杂 case 处理不如 shfmt 精细
手工整理 / 编辑器自带重排	人工方式	依赖个人习惯调整	零门槛	临时救急	优势：无依赖；不足：不可复现、团队无法统一、无法进 CI，正是 shfmt 要解决的痛点

说明：上述对比中，本技能提供的是围绕 shfmt 的知识与落地方案，而 ShellCheck、beautysh 等属于独立工具，具体安装方式与功能边界以各自官方说明为准。

5. 该技能的典型应用场景与实际体验情况

场景一：DevOps 团队的脚本风格统一

角色：SRE / 平台工程师。痛点：仓库里几十个部署脚本，有的是 4 空格，有的是制表符，git blame 经常追到“只改缩进”的提交。使用方式：先用 AI 确定团队参数（如 -i 2 -ci -bn），提交 .shfmt.toml 到仓库固化设置，再一次性 shfmt -w . 清理历史包袱。实际体验：一次性清理后 diff 会比较壮观，建议单独提一个“仅格式化”的提交，避免和业务改动混在一起；之后靠预提交钩子守住。

场景二：CI 流水线加一道格式门禁

角色：后端工程师。痛点：评审时反复回复“这里缩进不对”。使用方式：在 CI 中加一步 shfmt -d .，退出码非 0 即失败，并在日志里提示执行 shfmt -w。实际体验：门槛极低、收益立竿见影。注意 -d 的退出码语义为 0 表示无需更改、1 表示需要更改或出错，别把两者混为一谈。

场景三：编辑器里保存即格式化

角色：日常写脚本的开发者。痛点：写着写着风格漂移，回头再统一成本高。使用方式：VS Code 装 shell-format 并按技能给的 settings.json 配置 formatOnSave；Vim 用户用 ALE 或 formatprg。实际体验：配置一次，长期受益。注意 shellformat.path 要指向真实的 shfmt 路径，路径不对时格式化会静默失效。

场景四：老旧脚本迁移与报错排查

角色：接手历史项目的工程师。痛点：脚本 shebang 写 /bin/sh 却用了 bash 数组，或 shfmt 直接解析失败。使用方式：先 bash -n 或 sh -n 定位语法问题，再用 shfmt -ln posix 强制方言确认。实际体验：报错定位清晰。需注意 shfmt 不支持 # shfmt:ignore 这类行内忽略，想让某段代码不被重排，只能把它拆到单独文件并通过文件排除处理；另外 shfmt 不会自动折行，长命令仍需手动 \ 续行。

6. 该技能能为用户带来的价值

把隐性经验变成显性方案：方言选择、参数组合、编辑器配置、CI 退出码、报错排查顺序，原本散落在手册、博客和个人记忆里，现在可以一次性问清。
显著降低格式化的学习成本：不用通读 shfmt 文档就能直接拿到可粘贴的命令与配置，新手也能配出“保存即格式化 + 提交前拦截”的完整链路。
减少无效的评审往返：格式问题交给工具拦截，评审聚焦逻辑；纯风格改动不再淹没真实修改。
可复现、可传承的团队规范：.shfmt.toml + 预提交钩子 + CI 检查三件套，让风格约定从“口头约定”变成“强制机制”，人员流动也不会走样。
长期收益：格式化后的脚本可读性提升，接手成本下降；配合 -mn 压缩能力还能覆盖发布分发场景（技能明确提示压缩会移除注释与大量空格，仅用于分发、不用于开发）。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要先装 shfmt 吗？ 在所用 AI 工具的技能市场或技能库中，按英文名 shfmt-formatting 或技能 ID 13849 检索并启用即可，具体入口与命令以官方说明为准。shfmt 本体是否需要本地安装，取决于你是想“咨询方案”还是“真正执行命令”——后者需要本地有 shfmt 可执行文件，安装方式请以 shfmt 官方文档说明为准。

Q2：这个技能收费吗？ 技能本身的价格与授权方式取决于你所使用的 AI 平台的技能政策，本文不作假设，请以官方说明为准。

Q3：它和 ShellCheck 是什么关系？需要二选一吗？ 不需要。两者定位不同：ShellCheck 检查的是逻辑与健壮性问题（如引号误用、不可移植写法），shfmt 只负责格式。推荐组合是“shfmt 管排版，ShellCheck 管风险”，两者都可接入编辑器与 CI。

Q4：为什么我的脚本格式化后变化特别大，甚至像被重写了？ shfmt 会把多语句拆成独立行、统一 if/then/else 与 case 的换行与缩进、规范操作符间距，所以首次全量格式化 diff 通常很大。建议先 shfmt -d 预览、单独提交“仅格式化”变更，再靠预提交钩子维持；若某段代码必须保留原样，可将其拆到独立文件并通过文件排除处理（技能明确指出不支持行内忽略注释）。

Q5：shfmt 报解析错误，或者方言识别不对怎么办？ 先用 bash -n script.sh 或 sh -n script.sh 检查语法，语法通过后仍有问题，则用 shfmt -ln bash 或 shfmt -ln posix 强制指定方言。同时记得让脚本 shebang 与实际方言匹配，这是技能反复强调的最佳实践之一。