PHPBench 必须作为开发依赖安装，不可全局安装；正确方式是 composer require --dev phpbench/phpbench，命令位于 vendor/bin/phpbench，需配置扫描路径或使用 --filter 否则静默退出。
PHPBench 不是靠 Composer “安装”就能直接用的，它必须作为开发依赖引入项目，且默认不提供全局命令；直接 composer global require phpbench/phpbench 会踩坑——命令不可用、版本冲突、PHP 版本不匹配。
为什么不能用 global require
PHPBench 的 phpbench 可执行文件依赖当前项目的 autoloader 和配置上下文，global 安装后找不到 vendor/autoload.php，运行时大概率报错 Class 'PhpBench\Registry\Config' not found 或直接提示 Command "phpbench" is not defined。它不是 Laravel Valet 那类设计为全局工具的包。
- global 安装绕过项目 autoloader，无法加载扩展和自定义 benchmark 类
- 多个项目共用一个 global 版本，但不同项目可能需要 PHPBench v1.x（PHP 7.4）或 v2.x（PHP 8.1+）
- CI 环境中 global 安装不可重现，容易导致测试失败
正确引入方式：dev 依赖 + 本地 bin
必须在项目根目录执行：
composer require --dev phpbench/phpbench
完成后，phpbench 命令会出现在 vendor/bin/phpbench。所有操作都基于这个路径，而不是全局命令。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
立即学习“PHP免费学习笔记（深入）”；
- 务必加
--dev，它不属于运行时依赖 - 不要手动改
PATH指向vendor/bin——不同项目路径不同，CI 中也不稳定 - 推荐在
composer.json的scripts里定义快捷命令，比如："bench": "phpbench run --report=aggregate" - 运行时用
./vendor/bin/phpbench run benchmarks/MyClassBench.php，路径必须写对
常见报错与对应解法
遇到 PHP Fatal error: Uncaught Error: Class 'PhpBench\Benchmark\Metadata\Annotations\Groups' not found？这是 PHPBench v2 引入的注解类名变更，老代码用了 v1 的 @Groups 注解但装了 v2。
- 检查
composer show phpbench/phpbench输出的版本号 - v1 → v2 升级需改注解：把
@Groups({"unit"})改成@Groups({"unit"})（写法没变），但实际要确认是否用了已废弃的@ParamProviders等——v2 改叫@ParamProvider - 若项目还依赖旧版
phpunit/phpunit（如 9.5），可能和 PHPBench v2 的phpunit依赖冲突，需统一升级或锁死phpbench/phpbench:^1.2 - Windows 下路径分隔符问题：避免在
phpbench.json里写benchmarks\*.php，统一用正斜杠benchmarks/*.php
最常被跳过的一步：PHPBench 默认不扫描子目录下的 *Bench.php 文件，必须显式配置 path 或用 --filter，否则 run 命令静默退出、零报告——这不是 bug，是设计如此。
