configure-formatting

/configure:formatting

检查代码格式化工具，并按照现代最佳实践进行配置。

何时使用此技能

在以下情况下使用此技能……	在以下情况下采用其他方式……
为项目设置 Biome、Prettier、Ruff format 或 rustfmt	运行现有格式化工具（biome format、ruff format）
从 Prettier 迁移到 Biome，或从 Black 迁移到 Ruff	修复特定文件中的个别格式问题
审核格式化工具配置是否完整且符合最佳实践	配置 lint 规则（改用 /configure:linting）
添加保存时自动格式化和 CI 格式检查	仅设置 pre-commit 钩子（改用 /configure:pre-commit）
在单体仓库中统一格式设置	手动编辑 .editorconfig 或 .vscode/settings.json

上下文

• Biome 配置：!find . -maxdepth 1 -name \'biome.json\'
• Prettier 配置：!find . -maxdepth 1 \( -name '.prettierrc*' -o -name 'prettier.config.*' \)
• Ruff 配置：!grep -l 'tool.ruff.format' pyproject.toml
• Black 配置：!grep -l 'tool.black' pyproject.toml
• Rustfmt 配置：!find . -maxdepth 1 \( -name 'rustfmt.toml' -o -name '.rustfmt.toml' \)
• EditorConfig：!find . -maxdepth 1 -name \'.editorconfig\'
• Package JSON：!find . -maxdepth 1 -name \'package.json\'
• Python 项目：!find . -maxdepth 1 -name \'pyproject.toml\'
• Rust 项目：!find . -maxdepth 1 -name \'Cargo.toml\'
• Pre-commit：!find . -maxdepth 1 -name \'.pre-commit-config.yaml\'
• 项目规范：!find . -maxdepth 1 -name \'.project-standards.yaml\'

参数

从 $ARGUMENTS 解析：

• --check-only：报告合规状态，不进行修改
• --fix：自动应用所有修复，无需提示
• --formatter <formatter>：覆盖格式化工具检测结果（biome、prettier、ruff、rustfmt）

版本检查

重要：在指出格式化工具已过时时，先使用 WebSearch 或 WebFetch 核实最新版本：

1. Biome：查看 biomejs.dev 或 GitHub releases
2. Prettier：查看 prettier.io 或 npm
3. Ruff：查看 docs.astral.sh/ruff 或 GitHub releases
4. rustfmt：随 Rust 工具链捆绑发布——查看 Rust releases

执行

执行以下代码格式化配置工作流：

第 1 步：检测项目语言和现有格式化工具

检查语言标识和格式化工具配置：

标识	语言	检测到的格式化工具
带有格式化配置的 biome.json	JavaScript/TypeScript	Biome
.prettierrc.*	JavaScript/TypeScript	Prettier
pyproject.toml [tool.ruff.format]	Python	Ruff
pyproject.toml [tool.black]	Python	Black（旧版）
rustfmt.toml 或 .rustfmt.toml	Rust	rustfmt

现代格式化偏好：

• JavaScript/TypeScript：Biome（优先）或 Prettier
• Python：Ruff format（替代 Black）
• Rust：rustfmt（标准）

第 2 步：分析当前格式化工具配置

针对每个检测到的格式化工具，检查配置是否完整：

1. 配置文件是否存在并包含必要设置（缩进、行宽、引号等）
2. 是否配置了忽略模式
3. 是否在 package.json / pyproject.toml 中定义了格式化脚本
4. 是否配置了 pre-commit 钩子
5. 是否配置了 CI/CD 检查

第 3 步：生成合规报告

打印格式化的合规报告：

Code Formatting Compliance Report
==================================
Project: [name]
Language: [detected]
Formatter: [detected]

Configuration:  [status per check]
Format Options: [status per check]
Scripts:        [status per check]
Integration:    [status per check]

Overall: [X issues found]
Recommendations: [list specific fixes]

如果指定了 --check-only，则在此处停止。

第 4 步：安装并配置格式化工具（如果使用 --fix 或用户确认）

根据检测到的语言和格式化工具偏好，进行安装和配置。使用 REFERENCE.md 中的配置模板。

1. 安装格式化工具包
2. 创建配置文件（biome.json、.prettierrc.json、pyproject.toml 中的配置段、rustfmt.toml）
3. 在 package.json 或 Makefile/justfile 中添加格式化脚本
4. 如有需要，创建忽略文件（.prettierignore）

第 5 步：集成 EditorConfig

创建或更新 .editorconfig，使其设置与格式化工具配置一致。

第 6 步：处理迁移（如适用）

如果检测到旧版格式化工具（Prettier -> Biome、Black -> Ruff）：

1. 导入现有配置
2. 安装新的格式化工具
3. 移除旧的格式化工具
4. 更新脚本
5. 更新 pre-commit 钩子

使用 REFERENCE.md 中的迁移指南。

第 7 步：配置 pre-commit 钩子

使用相应的钩子仓库，将格式化工具添加到 .pre-commit-config.yaml。

第 8 步：配置 CI/CD 集成

在 GitHub Actions 工作流中添加格式检查步骤。

第 9 步：配置编辑器集成

创建或更新 .vscode/settings.json，设置保存时格式化；并在 .vscode/extensions.json 中配置格式化工具扩展。

第 10 步：更新规范跟踪

更新 .project-standards.yaml：

components:
  formatting: "2025.1"
  formatting_tool: "[biome|prettier|ruff|rustfmt]"
  formatting_pre_commit: true
  formatting_ci: true

第 11 步：打印完成报告

打印所做更改、新增脚本和后续步骤（运行格式化、验证 CI、启用保存时格式化）的摘要。

有关详细配置模板、迁移指南和 pre-commit 配置，请参阅 REFERENCE.md。

Agent 优化

上下文	命令
快速合规检查	/configure:formatting --check-only
自动修复所有问题	/configure:formatting --fix
检查 Biome 格式	biome format --check --reporter=github
检查 Prettier 格式	`npx prettier --check . 2>&1
检查 Ruff 格式	ruff format --check --output-format=github
检查 rustfmt 格式	`cargo fmt --check 2>&1

标志

标志	说明
--check-only	报告状态，不提供修复方案
--fix	无需提示，自动应用所有修复
--formatter <formatter>	覆盖格式化工具检测结果（biome、prettier、ruff、rustfmt）

示例

# Check compliance and offer fixes
/configure:formatting

# Check only, no modifications
/configure:formatting --check-only

# Auto-fix and migrate to Biome
/configure:formatting --fix --formatter biome

错误处理

• 检测到多个格式化工具：警告存在冲突，并建议迁移
• 未找到包管理器：无法安装格式化工具，报错
• 配置无效：报告解析错误，并提供替换为模板的选项
• 格式冲突：报告将被重新格式化的文件

另请参阅

• /configure:linting - 配置代码检查工具
• /configure:editor - 配置编辑器设置
• /configure:pre-commit - 配置 pre-commit 钩子
• /configure:all - 运行所有合规检查
• Biome 文档：https://biomejs.dev
• Ruff 文档：https://docs.astral.sh/ruff
• rustfmt 文档：https://rust-lang.github.io/rustfmt