74 lines
4.1 KiB
Markdown
74 lines
4.1 KiB
Markdown
---
|
||
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）
|
||
1. **Baseline**
|
||
- 记录当前状态：`git status --porcelain`
|
||
- 明确范围（默认只处理变更文件）：
|
||
- staged：`git diff --name-only --cached`
|
||
- unstaged：`git diff --name-only`
|
||
- untracked：`git ls-files -o --exclude-standard`
|
||
|
||
2. **Detect Toolchain（prefer repo truth）**
|
||
- 优先用仓库既有入口脚本 / 配置：
|
||
- JS/TS：`package.json` scripts（`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（仅在仓库已固定时使用）
|
||
- 禁止默认“引入新 formatter/linter 配置”；缺配置时只做最小手工调整，并先确认是否允许落地配置文件。
|
||
|
||
3. **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...>`（以项目脚本为准）
|
||
|
||
4. **Guardrails**
|
||
- 只做风格与格式：不改变行为、不改 public API、不做重构。
|
||
- 如格式化导致 diff 暴涨（文件数/行数过大）：先停下，给出原因与两种方案让用户选：
|
||
1) 仅格式化本次改动文件（推荐默认）
|
||
2) 全仓库统一格式（通常需要单独 PR/提交）
|
||
|
||
5. **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）：以仓库配置为准；必要时调整例外配置但需先确认
|