本地安装+显式配置文件+composer脚本封装是唯一稳定可靠的集成方式，因全局安装易致版本冲突、path未配置导致command not found、默认规则随版本变动、缺--dry-run易误判、配置文件名/路径/返回值格式错误均会失效。
本地安装 + 显式配置文件 + Composer 脚本封装，是唯一稳定可靠的集成方式。全局安装、省略配置、裸跑命令，全都会在 CI 或换环境时出问题。
为什么不能直接用 php-cs-fixer 命令？
因为 Composer 默认不把 vendor/bin 加进系统 PATH，尤其在 CI 环境或新机器上，php-cs-fixer 命令大概率报 command not found。即使本地能运行，也可能是你之前手动加过 PATH，别人拉代码就失败。
- 全局安装（
composer global require）会让所有项目共享一个版本，但不同项目可能依赖 PHP 7.4 或 PHP 8.2，规则集（如@PHP80Migration）会直接失效 - 不指定配置文件时，PHP CS Fixer v3 会加载内置默认规则——这些规则随版本升级变动，今天格式化结果和下周可能完全不同
- 不加
--dry-run就执行fix，默认其实是只扫描不写入，你会误以为“没反应”，其实它啥都没干
.php-cs-fixer.php 必须这么写才生效
文件名必须是 .php-cs-fixer.php（开头带点，不是 .php_cs，也不是 php-cs-fixer.php），且必须放在项目根目录。内容必须返回一个 PhpCsFixer\Config 实例，不能是数组或 JSON。
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
-
setFinder()必须显式调用，否则只处理当前目录下的*.php文件，src/和tests/会被忽略 - 务必
exclude('vendor')和ignoreVCS(true)，否则扫描.git目录可能卡住或报错 - 规则里写
'@PSR12' => true，不是'psr12' => true，拼错键名会静默跳过，不报错也不生效 - 加
setCacheFile('.php-cs-fixer.cache')，大项目二次运行能快 3–5 倍
Composer 脚本怎么配才不踩坑？
在 composer.json 的 "scripts" 里定义命令，别手敲长路径。但注意：脚本里不能写 ./vendor/bin/php-cs-fixer，而要直接写 php-cs-fixer —— Composer 会自动把 vendor/bin 加进子进程 PATH。
-
"cs-fix": "php-cs-fixer fix --verbose"：日常修复，加--verbose看哪些文件被处理了 -
"cs-check": "php-cs-fixer fix --dry-run --diff --using-cache=no"：CI 里用，--using-cache=no防止缓存干扰检查结果 - 不要写
"format": "vendor/bin/php-cs-fixer fix"，Windows 下.bat后缀和 Linux 路径不兼容，脚本会挂 - 如果想限制只修某个目录，脚本里写成
"cs-fix-app": "php-cs-fixer fix app/ --verbose"，比改配置更灵活
Git 提交前自动格式化的真实成本
用 pre-commit 钩子自动跑 composer cs-fix 看似省事，但有三个硬伤：
- 首次提交前没运行过
composer install，钩子里的composer命令根本不存在 - 格式化耗时超过 10 秒（常见于 >5k 行项目），开发者会下意识
git commit --no-verify绕过，规范形同虚设 - 如果
.php-cs-fixer.php里漏了ignoreVCS(true)，钩子会尝试格式化.git/下的临时文件，导致 commit 失败
真正可控的做法是：只在 CI 流水线里跑 composer cs-check，失败即阻断；开发阶段靠 IDE 集成（如 PhpStorm 指定 vendor/bin/php-cs-fixer 为外部工具）或手动 composer cs-fix，留出判断余地。
