4.1 KiB
4.1 KiB
name: style-cleanup
description: Clean up formatting and code style with the repo’s existing toolchain (clang-format/black/isort/flake8/pre-commit/etc). Triggers: 整理代码风格, 格式化, format, fmt, lint fix, clang-format, black, isort.
Style Cleanup Workflow（整理代码风格 / 格式化）
When to Use
- “整理代码风格 / 格式化 / format / fmt / lint fix”
- 合并前做一次风格对齐（不做语义级重构）
- 批量改动后，希望把格式化与机械性风格问题收敛到可控 diff
Inputs（required）
- Scope：仅本次改动文件（默认）｜全仓库｜指定目录/文件类型
- Languages：自动识别；如为多语言仓库请确认优先级
- Verification：至少一个可执行的验证命令（如未知，先问/再推断）
Procedure（default）
-
Baseline
- 记录当前状态：
git status --porcelain - 明确范围（默认只处理变更文件）：
- staged：
git diff --name-only --cached - unstaged：
git diff --name-only - untracked：
git ls-files -o --exclude-standard
- staged：
- 记录当前状态：
-
Detect Toolchain（prefer repo truth）
- 优先用仓库既有入口脚本 / 配置：
- JS/TS：
package.jsonscripts（format/lint/lint:fix）、prettier/biome/eslint 配置 - Python：
pyproject.toml/.flake8/.pylintrc/.pre-commit-config.yaml - C/C++：
.clang-format（唯一真相），可选.clang-tidy - Shell：
shfmt/shellcheck（若仓库已使用） - Markdown：prettier/markdownlint（仅在仓库已固定时使用）
- JS/TS：
- 禁止默认“引入新 formatter/linter 配置”；缺配置时只做最小手工调整，并先确认是否允许落地配置文件。
- 优先用仓库既有入口脚本 / 配置：
-
Apply（format first, then lint）
- 先 formatter（会改文件），再 lint（检查），再 lint --fix（如有），最后再跑一次 check 确认干净。
- 默认只处理目标文件集合；避免全仓库 reformat（除非用户明确要求）。
- 典型命令（按仓库实际替换）：
- C++：
clang-format -i <files...>；CI 校验：clang-format --dry-run --Werror <files...> - Python：
black <files...>+isort <files...>；或pre-commit run --files <files...> - JS/TS：
npm run format -- <files...>/pnpm .../npx prettier -w <files...>（以项目脚本为准）
- C++：
-
Guardrails
- 只做风格与格式：不改变行为、不改 public API、不做重构。
- 如格式化导致 diff 暴涨（文件数/行数过大）：先停下，给出原因与两种方案让用户选：
- 仅格式化本次改动文件（推荐默认）
- 全仓库统一格式（通常需要单独 PR/提交）
-
Verify
- 跑最小验证命令（仓库已有命令优先）。
- 若无法运行（缺环境/缺权限/缺依赖）：说明原因，并给出替代验证（例如 formatter 二次运行无 diff、lint 输出为 0）。
Playbook as Authority（如果项目 vendoring 了本 Playbook）
当目标仓库包含 docs/standards/playbook/docs/（或直接包含 docs/tsl|cpp|python/...），风格决策参考：
- TSL：
docs/tsl/code_style.md、docs/tsl/naming.md、docs/tsl/toolchain.md - C++：
docs/cpp/code_style.md、docs/cpp/naming.md、docs/cpp/toolchain.md - Python：
docs/python/style_guide.md、docs/python/tooling.md、docs/python/configuration.md
Output Contract（stable）
- Scope：实际处理范围（文件/目录/语言）
- Toolchain：使用了哪些工具与配置依据
- Commands：实际执行命令（按顺序）
- Changes：修改文件列表 + 改动规模概览
- Remaining：仍未修复的问题（分类：formatter / lint / style）+ 下一步建议
Success Criteria
- formatter 二次运行无新增 diff
- lint/检查命令通过（或仅剩已确认的例外）
- 未引入语义变更（仅格式/风格）
Failure Handling
- 工具缺失：优先提示安装方式或替代命令；无法解决则退回“最小手工风格修复 + 明确未覆盖项”
- 规则冲突（如 black vs flake8）：以仓库配置为准；必要时调整例外配置但需先确认